/**************************************************************************\
 *
 *  This file is part of the Coin 3D visualization library.
 *  Copyright (C) by Kongsberg Oil & Gas Technologies.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  ("GPL") version 2 as published by the Free Software Foundation.
 *  See the file LICENSE.GPL at the root directory of this source
 *  distribution for additional information about the GNU GPL.
 *
 *  For using Coin with software that can not be combined with the GNU
 *  GPL, and for taking advantage of the additional benefits of our
 *  support services, please contact Kongsberg Oil & Gas Technologies
 *  about acquiring a Coin Professional Edition License.
 *
 *  See http://www.coin3d.org/ for more information.
 *
 *  Kongsberg Oil & Gas Technologies, Bygdoy Alle 5, 0257 Oslo, NORWAY.
 *  http://www.sim.no/  sales@sim.no  coin-support@coin3d.org
 *
\**************************************************************************/

// *************************************************************************

/*!
  \defgroup actions Action Classes

  Actions are objects that traverse a scene graph to drive some
  scene-related process, one example being OpenGL rendering, and
  another being ray picking.

  At the most basic level, most action management will be done for the
  user behind the scenes in an SoSceneManager object, and the only
  actions one might need to get acquainted with are SoSearchAction and
  SoWriteAction.

  For more advanced usage of Coin, one might want (or need) to take full
  control over driving all the actions oneself, in which case one will
  also need to know about the SoGLRenderAction, SoHandleEventAction,
  SoGetBoundingBoxAction, and SoRayPickAction.

  The remaining actions are mostly more special-purpose actions of
  various kinds, except for the SoCallbackAction.

  Before going to the step of implementing an extension action, one
  should really take a good look at the SoCallbackAction class, which
  is a general-purpose action that can be used as the framework for
  implementing almost any traversal-based process, with callback-hooks
  for all kinds of events that happen during traversal.  In most cases,
  one can avoid the hassle of writing a new action, and just use
  SoCallbackAction instead.

*/

// *************************************************************************

/*!
  \defgroup base Base Classes

  This group is just a lot of basic types for linear algebra, string
  manipulation and misc. other utilities.

*/

// *************************************************************************

/*!
  \defgroup bundles Bundle Classes

  The bundle classes are internal to Coin.
*/

// *************************************************************************

/*!
  \defgroup caches Cache Classes

  The cache classes are internal to Coin.
*/

// *************************************************************************

/*!
  \defgroup details Detail Classes

  Detail classes are objects that deliver additional information
  wherever the SoPrimitiveVertex class is used.  This goes for ray
  picking results, and it also goes for primitive generation by
  SoShape classes for the SoCallbackAction class and fallback shape
  rendering through primitive generation (a useful debugging trick
  when debugging for instance raypicking).

*/

// *************************************************************************

/*!
  \defgroup draggers Dragger Classes

  Draggers are interactive components in the scene graph that respond
  to, and are controlled by mouse and keyboard events.  They are used in
  manipulators as the user interface for the manipulation action, often
  many draggers combined at the same time.

  \see manips
*/

// *************************************************************************

/*!
  \defgroup elements Element Classes

  The element classes in Coin are the containers of state information
  during action traversals of scene graphs.  One element usually
  corresponts to one item of information, or sometimes a group of
  related information values.  The elements work like a stack that is
  pushed and popped as the action traverses in and out of SoSeparator
  nodes, and the action will always just inspect the top of the stack
  when it needs to know a value.

  Elements are internal implementation details of the workings of
  nodes and actions, and is not something one needs to worry about
  before writing ones own extension nodes.  Writing extension elements
  is even more removed from plain Open Inventor usage, but is fully
  possible for the experienced Open Inventor developer.

*/

// *************************************************************************

/*!
  \defgroup engines Engine Classes

  Engines are scene based objects that convert between field values of
  various types or performs computations on them.  The most versatile
  engine is the SoCalculator engine, which you can write your own
  mathematical expressions to to get it to do almost anything.  The
  other engines are more custom-tailored for specific purposes.

*/

// *************************************************************************

/*!
  \defgroup errors Error Handling Classes

  The error classes are static classes that contain a callback pointer
  for handling errors of the given type.  Coin has default handlers
  for displaying all the types, but these can be overridden by
  applications by setting other callbacks.

*/

// *************************************************************************

/*!
  \defgroup events Event Classes

  These classes are te event types you can send to a scene graph
  through the SoHandleEventAction.  They are a pretty direct mapping
  from the various system event types you will have on all the host
  architectures.

*/

// *************************************************************************

/*!
  \defgroup fields Field Classes

  The fields are the data containers in the scene graph.  Nodes and
  engines all use fields to store their public data.

  Fields can be inter-connected, causing changes at one location in a
  scene graph to cause other parts of the scene graph to automatically
  also get updated.  Direct field-to-field connections will cause
  values to get duplicated, while field connections together with
  engines can create complex networks for such updating that include
  mathematical computations and logical operations.  Field connections
  are uni-directional, but setting up a connection in both directions
  will cause a bi-directional connection.

  Fields are first divided into two groups; "single fields" and "multi
  fields".  Single-fields contain just one value, while multi-fields
  can contain many values or even none at all.

  Besides fields that are part of nodes, you also have "global fields".
  The "realtime" field is one such field.

  The fields in VRML97 nodes have additional semantics.  Some are
  "event_in" and some are "event_out", listening for events or
  triggering events.  "event_in" events should not be read from, and
  "event_out" fields should not be written to.

*/

// *************************************************************************

/*!
  \defgroup general Miscellaneous Classes

*/

// *************************************************************************

/*!
  \defgroup manips Manipulator Classes

  Manipulators are objects you can swap back and forth into a scene
  graph at locations where you have an SoTransform node.  They take
  the place of the SoTransform, continue to act like the SoTransform,
  but in addition give the user a 3D user interface, using draggers,
  for controlling the transform.  When the user is done manipulating,
  the manipulator can swap itself back out, replacing itself with an
  SoTransform that represent the new transform value.

  Manipulators is one of the concepts that really made Open Inventor
  stand out against the alternatives when it came out.

  \see draggers
*/

// *************************************************************************

/*!
  \defgroup nodekits NodeKit Classes

  Wrapping ones head around when, how, and why to create nodekits can
  be difficult in the beginning.  When do you write a nodekit, and
  when do you write a custom node?  It is easy to think in those terms
  in the beginning, but it is often not an either/or situation.

  The concept of nodekits is to modularize useful, potentially
  repeated sub-structures you have in your scene graph as it
  approaches some level of complexity.  They are especially useful if
  you might need to rearrange the structure of the sub-structure in
  the future, which you probably will.

  On file, a nodekit is like a macro for the scene graph.  The nodekit
  will not expose its internal structure, but when read in it will
  create the node structure internally.  The node structure can even
  have optional parts that are only expanded if necessary.

  A nodekit will give you access to its "slots" in the internal
  structure through its fields.  Only those fields should be the user
  interface for the nodekit, the rest of the substructure should be
  completely automatic, derived from those slot fields.

  To return to the question on whether to implement a custom node or a
  nodekit, the answer is to think of what exactly is really custom
  about what you need to implement, and trim that down to the atomic
  level (but please stop trimming before you trim away all meaning).
  If there is nothing really custom in what you want to implement,
  then it is likely that implementing it as a nodekit is what you
  ought to do.  However, if you do have to do somethingcustom that
  Coin doesn't support, then implement that part as a custom node, and
  then, if it seems worthwhile, implement the nodekit you need to
  bundle up this custom part with an auxiliary support structure to
  achieve what you set out to achieve.

  For VRML97, you have something called PROTOs, which is something
  similar to nodekits, except they are not very accessible from C++, as
  opposed to nodekits.

*/

// *************************************************************************

/*!
  \defgroup nodes Node Classes

  This is the set of nodes Coin implements using the original Open
  Inventor pattern, meaning they read and write to and from files
  using the Inventor/VRML1 format, and produce side-effects for
  subsequent siblings under the same SoSeparator node during action
  traversal.

  A subset of these nodes constitute the VRML1 format, and a bigger
  subset constitutes the Inventor format.  The rest of the nodes are
  extensions that are not part of any standardized format.

  For VRML97 nodes, see the \ref VRMLnodes page.

  The VRML1.0 specification is at
  http://www.web3d.org/x3d/specifications/vrml/VRML1.0/index.html

*/

// *************************************************************************

/*!
  \defgroup projectors Projector Classes

  The projector classes are used to convert between screenspace (2D)
  locations and locations in worldspace (3D).  They are mostly used in
  relation to user interaction with the mouse in the viewport.

*/

// *************************************************************************

/*!
  \defgroup sensors Sensor Classes

  Sensors are objects that monitor other objects for changes and invoke
  callbacks when changes occur.

*/

// *************************************************************************

/*!
  \defgroup shaders Shader Classes

  Coin-2.5 added support for Shaders. Shaders replace the fixed
  function vertex and fragment processing in OpenGL by letting the
  user define the processing that takes place at key points in the
  OpenGL pipeline. Vertex shaders handle the operations that occur on
  each vertex, while fragment shaders handle the operations that occur
  on each pixel. The SoShaderProgram node in Coin provides a
  convenient way of specifying the code for vertex and fragment
  shaders.

  Coin-3.0 expanded upon the shader support by adding support for
  OpenGL Vertex Attributes. When using shaders, programmers are no
  longer limited to the set of attributes that OpenGL defines
  (glColor, glNormal, glTexCoord etc.) You can now define your own
  per-vertex data and pass them to the shaders using the
  SoVertexAttribute node.

*/

// *************************************************************************

/*!
  \defgroup sound 3D Sound Support Classes

*/

// *************************************************************************

/*!
  \defgroup scxml State Chart XML Classes

  This set of classes is a basic implementation of State Chart XML.
  It is not complete, nor is it necessary conformant to those parts it
  implements.  It is however a decent start, and there are plans for
  implementing more parts of the specification.

  Currently Coin uses SCXML for managing 3D viewer user interaction
  (the non-model-interaction part) - the examiner navigation mode in
  layman terms - but with a more complete implementation of SCXML, the
  potential for more uses should be quite huge.

  The Draft Specification for SCXML is at http://www.w3.org/TR/scxml/.

  \since Coin 3.0

*/

// *************************************************************************

/*!
  \defgroup threads Portable Threads Abstraction Classes

  Coin implements a set of abstractions over the native threads data
  types that can be portably used across all the platforms Coin has
  been ported to.

*/

// *************************************************************************

/*!
  \defgroup VRMLnodes VRML97 Classes

  This is the set of items specified by VRML97, also known as VRML2.0.
  These nodes are different from VRML1/Inventor nodes in the way you
  structure them into scene-graphs, and in the requirements they set
  for traversing them correctly (VRML1/Inventor require that you
  traverse siblings on the left side before the node of interest,
  while for VRML2.0 this is not true).

  You can find out more about VRML97 in \ref vrml2refbook.

  The VRML97 specification is online at
  http://www.web3d.org/x3d/specifications/vrml/

*/

// *************************************************************************

/*!
  \defgroup hardcopy Vectorized Printing Classes

  The vectorized printing classes are for rendering to vector devices
  instead of raster devices.  You can use this to e.g. generate
  scalable PostScript images for printing instead of raster images
  that will become pixellated when you scale them up.

  See below for \ref hardcopy_overview.
*/

// *************************************************************************

/*!
  \defgroup XML XML related functions and objects

  Coin now has its own XML parser that also canb be used from client code.
*/

// *************************************************************************

/*!
  \defgroup profiler Scene Graph Profiling

  Coin includes some scene graph profiling functionality.  This
  functionality is intended for use during application development for
  identifying performance bottlenecks in Coin-based applications with
  regards to how Coin is being used and with regards to problems with
  how Coin is implemented.

  The profiling code can be enabled in existing Coin applications
  without the need of adding any code by enabling it through the use
  of some environment variables.  For particular profiling needs, the
  default behaviour you can trigger through environment variables
  might not work that well (you might have a specialized render
  pipeline that causes the output to be garbled) or focus on the
  information you need (the full application might perhaps add noise
  to the system that Coin won't separate out).  In such cases,
  programmatic access to the profiling subsystem will be necessary to
  get the better results.

  \since Coin 3.0

*/

// *************************************************************************

/*!
  \defgroup macros Miscellaneous Macros

  When extending Coin, there are a number of macros one needs to know
  about and use.

*/

// *************************************************************************

/*!
  \defgroup envvars Miscellaneous Environment Variables

  Various aspects of the Coin runtime behaviour can be controlled through
  setting different environment variables to some value.  Most of these
  variables are there for debugging and problem-workaround purposes, but
  a few are for telling Coin where to locate external resource files.

  Here we will set up a list of some of the environment variables Coin will
  check for and can alter behavior because of.

*/

// *************************************************************************