Doc/to_port/Base.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpBase OpenSG Base Library
   6
   7     \brief The Base Library contains fundamental classes, functions and,
   8            abstractions.
   9
  10     See \ref PageBase for details.
  11 */
  12
  13 /*! \defgroup GrpBaseBase Base
  14     \ingroup GrpBase
  15
  16     ToDo
  17 */
  18
  19 /*! \defgroup GrpBaseBaseBaseTypes BaseTypes
  20     \ingroup GrpBaseBase
  21
  22     ToDo
  23 */
  24
  25 /*! \defgroup GrpBaseBaseBaseTypeTraits BaseTypesTraits
  26     \ingroup GrpBaseBase
  27
  28     ToDo
  29 */
  30
  31 /*! \defgroup GrpBaseBaseColors Colors
  32     \ingroup GrpBaseBase
  33
  34     ToDo
  35 */
  36
  37 /*! \defgroup GrpBaseBaseCmpTimeFn Compile Time Functions
  38     \ingroup GrpBaseBase
  39
  40     ToDo
  41 */
  42
  43 /*! \defgroup GrpBaseBaseConstants Constants
  44     \ingroup GrpBaseBase
  45
  46     ToDo
  47 */
  48
  49 /*! \defgroup GrpBaseBaseFileSystem FileSystem
  50     \ingroup GrpBaseBase
  51
  52     ToDo
  53 */
  54
  55 /*! \defgroup GrpBaseBaseGLConstants GLConstants
  56     \ingroup GrpBaseBase
  57
  58     ToDo
  59 */
  60
  61 /*! \defgroup GrpBaseBaseHelper Helper
  62     \ingroup GrpBaseBase
  63
  64     ToDo
  65 */
  66
  67 /*! \defgroup GrpBaseBaseInitExit Initialization / Termination
  68     \ingroup GrpBaseBase
  69
  70     ToDo
  71 */
  72
  73 /*! \defgroup GrpBaseBaseMath Math
  74     \ingroup GrpBaseBase
  75
  76     ToDo
  77 */
  78
  79 /*! \defgroup GrpBaseBaseMathObj Objects
  80     \ingroup GrpBaseBaseMath
  81
  82     ToDo
  83 */
  84
  85 /*! \defgroup GrpBaseBaseMathFn Functions
  86     \ingroup GrpBaseBaseMath
  87
  88     ToDo
  89 */
  90
  91 /*! \defgroup GrpBaseBaseMatrixFn Matrix Utility Functions
  92     \ingroup GrpBaseBaseMath
  93
  94     ToDo
  95 */
  96
  97 /*! \defgroup GrpBaseBaseMiscFn Miscellaneous Functions
  98     \ingroup GrpBaseBase
  99
 100     ToDo
 101 */
 102
 103 /*! \defgroup GrpBaseBaseMultiThreading Multithreading
 104     \ingroup GrpBaseBase
 105
 106     ToDo
 107 */
 108
 109 /*! \defgroup GrpBaseBaseRefCountFn Reference Count Functions
 110     \ingroup GrpBaseBase
 111
 112     ToDo
 113 */
 114
 115 /*! \defgroup GrpBaseBaseStringFn String Functions
 116     \ingroup GrpBaseBase
 117
 118     ToDo
 119 */
 120
 121 /*! \defgroup GrpBaseBaseTypeSystem TypeSystem
 122     \ingroup GrpBaseBase
 123
 124     ToDo
 125 */
 126
 127 /*! \defgroup GrpBaseBaseVolume Volume
 128     \ingroup GrpBaseBase
 129
 130     ToDo
 131 */
 132
 133
 134 /*! \defgroup GrpBaseNetwork Network
 135     \ingroup GrpBase
 136
 137 The network part of OpenSG contains all objects used for network
 138 communication. This objects are mainly used by OpenSG-Cluster support
 139
 140 */
 141
 142 /*! \defgroup GrpBaseSTLHelpers STLHelpers
 143     \ingroup GrpBase
 144
 145     STLHelpers are little structures and classes that are need to run STL
 146     algorithms or to use STL containers.
 147  */
 148
 149 /*! \page PageBase Base
 150
 151 \latexonly Starter:NewChapter \endlatexonly
 152
 153 All OpenSG symbols are part of the OSG name space, and they have no prefix.
 154 The actual files, including headers, all use the OSG prefix.
 155
 156 */
 157
 158 /*! \page PageBaseTypes Base Types
 159
 160 As one goal of OpenSG is the ability to run programs on a lot of different
 161 platforms, especially Unix and Windows, we have our own types which are
 162 guaranteed to have the same size on all platforms.
 163
 164 We have our own signed and unsigned integers in all useful
 165 sizes: Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64 as well as the
 166 two usual float sizes Real32 and Real64. Some useful constant are available:
 167 Eps, Pi, Inf and NegInf. A useful construct for template programming is the
 168 TypeConstants<type> structure, which defines some standard functions/values
 169 for the given type, see OSGBaseTypes.h for details.
 170
 171 */
 172
 173 /*! \page PageBaseLog Log
 174
 175 All output that OpenSG generates is channeled through the Log class, which is
 176 defined in OSGLog.h. OpenSG supplies a global Log object that is used by the
 177 library, but the application can create its own logs, if needed.
 178
 179 Every log message has one specific level. Available levels are FATAL, WARNING,
 180 NOTICE, INFO and DEBUG. They are also numbered from 0 to 5. The verbosity of
 181 the system can be controlled by ignoring messages of specific levels. This can
 182 be achieved by calling osgLog().setLogLevel( <enum> ); or by setting the
 183 environment variable OSG_LOG_LEVEL.
 184
 185 The system log has two different interfaces. One is based on C++ streams, one
 186 is based on C printf semantics.
 187
 188 The stream interface can be used by using SFATAL, SWARNING, SNOTICE or SINFO
 189 instead of cout or cerr. Note that there is no SDEBUG for efficiency reasons,
 190 as FDEBUG can be compiled out. These print the position in the code where the
 191 log is executed. For multi-line outputs you'll only want that on the first
 192 line, for the other lines use PFATAL, PWARNING, PNOTICE or PINFO.
 193
 194 To synchronize multiple outputs from various threads all S* commands lock the
 195 stream. You have to use 'osg::endLog' (e.g. SFATAL << "Message" << endLog;) to
 196 unlock the stream output.
 197
 198 Example: SINFO << "Line 1 of message 1" << endl; PINFO << "line2 of message 1"
 199 << endLog; SINFO << "Message 2" << endLog;.
 200
 201 The C interface tries to mimic the printf semantics. The following functions
 202 can be used for that: FFATAL, FWARNING, FNOTICE, FINFO and FDEBUG. The only
 203 difference to printf is that they have to be called with double parentheses,
 204 i.e. FWARNING(("What do you mean by %s?", s));. The nice thing about the C
 205 style interface is that the whole output can be compiled out. Actually, the
 206 FDEBUG (( )) are only compiled in when OSG_DEBUG is set. The OSG_DEBUG define
 207 is automatically set while compiling the system in debug (default) mode.
 208
 209 The user can activate/deactivate various elements per log message at runtime
 210 by changing the LogHeaderElem mask. The following elements are supported right
 211 now:
 212
 213 LOG_BEGIN_NEWLINE_HEADER (creates an extra newline in front of every output),
 214 LOG_TYPE_HEADER (writes the Level (e.g. WARNING) as first element),
 215 LOG_TIMESTAMP_HEADER (writes a timestamp), LOG_MODULE_HEADER (writes the name
 216 of the current module), LOG_FILE_HEADER (writes the source file name),
 217 LOG_LINE_HEADER (writes the source line number) and LOG_END_NEWLINE_HEADER
 218 (creates an extra newline at the end)
 219
 220 When unchanged, the time stamp will be the time in seconds since the program
 221 started. The user can set/reset the time stamp at any time (e.g.
 222 osgLog().resetRefTime()).
 223
 224 */
 225
 226 /*! \page PageBaseTime Time & Date
 227
 228 To wrap time and date handling we have a little abstraction for them.
 229
 230 getSystemTime() returns the current time since system has been started in
 231 seconds, using the highest resolution timer available.
 232
 233 The Date class provides a second resolution time stamp, factored into second,
 234 minute, hour, day, month and year. Date::setSystemDate() can be used to set it
 235 to the current date/time.
 236
 237 */
 238
 239 /*! \page PageBaseMath Math
 240
 241 Of course every scene-graph needs the basic math objects like Vectors, Points,
 242 Matrices, Quaternions etc., and OpenSG is no exception.
 243
 244 \section BaseMatrices Matrices
 245
 246 OpenSG matrices are similar to the OpenGL matrices in their storage structure
 247 and conventions, i.e. a matrix is per default a 4x4 Real32 matrix, and the
 248 multiplication convention is just like OpenGL's: v'=M*v.
 249
 250 The matrix is stored column major and access methods respect the storage
 251 format, i.e. matrix[0] yields the first column. This is also true for the
 252 vector-based constructor. However, the constructor taking 16 single elements
 253 expects its parameters row-major like the matrix is written on paper.
 254
 255 The positive side effect of this setup is the ability to access the base
 256 vectors of the matrix' coordinate space by accessing the vectors, i.e.
 257 matrix[3] is the translation to the origin of the local coordinate space. This
 258 is useful if you want to create your matrices from vectors, if you don't want
 259 to do that, don't worry about it.
 260
 261 Setting the contents of a matrix is done by the setValues() methods, accessing
 262 the values via the [] operator for access to single columns or by using
 263 getValues() to get a pointer to the first element. In general most classes in
 264 OpenSG that keep an array of elements allow access to them via getValues().
 265
 266 If you need to create a matrix for a specific transformation, use the
 267 setTransform() methods, which create a matrix that executes the given
 268 transformation.
 269
 270 Matrices also supply the standard set of matrix operations like det(), det3(),
 271 invert(), transpose(), mult() and multLeft(). There are some variants that
 272 change the matrix in place, return their results in a different matrix or get
 273 their source data from a different matrix, see the class docs for details.
 274
 275 The default vector/point multiplication methods multMatrixVec() and
 276 multMatrixPnt() assume that the matrix only uses the standard 3x4 elements. To
 277 use the full 4x4 matrix use multFullMatrixPnt(). As Vectors have a w
 278 coordinate of 0, compared to points which have w = 1, they don't need a full
 279 transform.
 280
 281 \section BaseVectors Vectors/Points/Colors
 282
 283 OpenSG is different from most other systems in differentiating between
 284 vectors, points and colors.
 285
 286 Vectors are the most common class, and they should behave like every other
 287 vector library on the planet. They are templated to simplify having variants,
 288 and the standard ones that are available are Vec4ub, Vec2us, Vec2s, Vec2f,
 289 Vec3s, Vec3f and Vec4f. They have operators for the scalar operations, and
 290 methods for everything else, see the doxygen docs for osg::VectorInterface for
 291 details. Conceptually, the 3 element vector has a w coordinate of 0, thus
 292 there is no full matrix multiplication for vectors.
 293
 294 Points represent positions in space, and as such they are more restricted than
 295 vectors. The available variants are Pnt2f, Pnt3f and Pnt4f. Some vector
 296 operations (dot, cross, etc.) don't make sense for points. Points can be
 297 subtracted (creating a vector), scaled and a vector can be added to or
 298 subtracted from them. If you want to represent a position, use a point. It
 299 helps keeping the concepts in order and not mix up everything just because it
 300 has the same data. When multiplied with a matrix, the w coordinate is set
 301 as 1 for 3 element points.
 302
 303 If you really need to get from a point to a vector or vice versa, you can
 304 use
 305
 306 - Vector &osg::Point.subZero()
 307 - Point  &osg::Vector.addToZero()
 308
 309 to cast a point to a vector and back.
 310
 311 Colors are RGB vectors, which also have access functions to the named
 312 components. They also allow access via the HSV color model and scalar
 313 multiplication, but no other operations.
 314
 315 \section BaseQuaternions Quaternions
 316
 317 Quaternions are the standard way to represent rotations. OpenSG quaternions
 318 feature the standard set of methods to get and set the rotations, in variants
 319 for radians and degrees. The standard order of the components is x,y,z,w. The
 320 standard operations (length, normalize, mult) are available, as well as slerp
 321 and multVec.
 322
 323 */
 324
 325 /* \page PageBaseLine Line
 326
 327 A Line defines a ray in space. It is defined by an origin and a direction,
 328 which is stored normalized. Lines can be constructed from two points or
 329 directly from a point and a direction.
 330
 331 A line can be intersected with all the bounding volumes and geometry. Only the
 332 positive parameter range of the line is intersected.
 333
 334 The line can also find the closest point on itself to a given point or another
 335 line.
 336
 337 */
 338
 339 /* \page PageBasePlane Plane
 340
 341 A Plane defines a 3D infinite half-space. It is defined by a normal and the
 342 distance from the origin, and can be constructed from all useful combinations
 343 of points and vectors.
 344
 345 Planes can also be intersected with infinite lines, if needed. Points can be
 346 tested for lying on the plane, or being in the positive half-space of the
 347 plane.
 348
 349 */
 350
 351 /* \page PageBaseVolumes Volumes
 352
 353 Volumes are primarily used for bounding geometry to speed up culling or
 354 intersection tests. All Volumes are derived from Volume. The supported volumes
 355 are the usual BoxVolume, defined by min and max points, the SphereVolume,
 356 defined by center and radius, and the FrustumVolume, which is defined by 6
 357 planes and primarily used to define the viewing frustum.
 358
 359 Volumes are created empty (i.e. zero volume) and can be changed by extending
 360 them by a point or another volume. All volumes have a variety of access
 361 functions, some specific to the type of volume, some general. Every volume
 362 supports getBounds() to access the min/max points, getCenter() and
 363 getScalarVolume() to access the volume measure. Volumes can be intersected
 364 with points, lines and other volumes, and they can be transformed by a matrix.
 365
 366 Volumes can be in one of several states. The default state is valid, special
 367 states are invalid, empty, infinite and static. There are specific functions
 368 to set them to any one of those states and to check if they are in any of
 369 those states.
 370
 371 Invalid volumes have to be set to valid explicitly, before extending them has
 372 any effect. setEmpty() makes it valid implicitly. The states except empty
 373 define how extensions and intersections are handled. Invalid volumes stay
 374 invalid and ignore changes, static and infinite volumes keep their values and
 375 are not changed by extensions. Intersecting an infinite volume is always true,
 376 just as intersecting an empty volume is never true.
 377
 378 */
 379
 380 /* \page PageBaseThreads Threads
 381
 382 OpenSG supports a thread abstraction to support efficient threading on all
 383 supported platforms. On Windows that means Windows threads, on Irix sproc() is
 384 used, for every other system pthreads are used.
 385
 386 Every thread uses a Thread object for thread-specific data, most of which is
 387 needed for thread-safe data, see [threadsafety]. To create a new thread, the
 388 Thread object has a run() method, which executes a given function in a new
 389 thread.
 390
 391 For thread synchronization Lock and Barrier objects are available. They act
 392 like standard locks and barriers, see the doc for details.
 393
 394 */
 395
 396 /* \page PageBaseImage Image
 397
 398 Defines and holds a 1D/2D/3D image and optionally a mipmap pyramid and/or a
 399 list of equally sized frames with a single frameDelay. Various pixelTypes are
 400 supported to handle gray and RGB color images with or without alpha channel.
 401 The image data starts in the lower left (front) corner and all bytes for a
 402 single pixel (e.g. RGB) are stored sequentially in memory. They are not
 403 organized in separate layers or channels.
 404
 405 An Image is only a container for the pixel data and image description. It does
 406 not create or handle any OpenGL state elements. However, image objects are
 407 utilized to handle the data for texture (e.g. SimpleTextureMaterial) or bitmap
 408 objects (e.g. ImageForeground).
 409
 410 The system provides loaders and writers for various formats (see section
 411 [imageLoaderSection]). The graph loaders (e.g. OSGLoader, VRMLLoader) use
 412 image loaders to fetch the raster data.
 413
 414 */
 415
 416 /* \page PageBaseIDString IDString
 417
 418 A primitive string class. Mainly used for string IDs (e.g. node type names).
 419 It is not a generic class like the std::string implementation. It's only for
 420 internal use to built efficient maps for names, not for application use. If
 421 you need a string class use std::string instead.
 422
 423 We decided to create our own specific string class since the std::string did
 424 not provide all features we needed (e.g. shared memory pointer, automatic
 425 preferred pointer comparison when comparing objects)
 426
 427 */
 428
 429 /* \page PageBaseFunctors Functors
 430
 431 Functors are the main method for OpenSG to call configurable actions. Functors
 432 wrap calls to a standard function, to a member of a specific instance or to a
 433 member of the first parameter.
 434
 435 Functors will have to be redesigned for 1.1, as they don't compile using the
 436 Microsoft Visual Studio compiler. :( Thus we don't talk much about them here,
 437 if you need to add a new action or GL object, send us mail.
 438
 439
 440 */
 441
 442