Doc/to_port/Groups.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemNodeCoresGroups Groups
   6     \ingroup GrpSystemNodeCores
   7
   8 See \ref PageSystemNCGroups for details.
   9
  10 */
  11
  12 /*! \page PageSystemNCGroups Groups
  13
  14 \latexonly Starter:NewChapter \endlatexonly
  15
  16 Groups are all the NodeCores who can be used as interior nodes in the graph.
  17 These nodes can have and actually use their children.
  18
  19 \section NCGroupsGroup Group
  20
  21 A Group is the simplest NodeCore, it doesn't do much. If asked to do something
  22 it calls its children to do the same thing, if asked for information it
  23 gathers it from the children. It does not intoduce a new transformation.
  24
  25 \section NCGroupsSwitch Switch
  26
  27 A Switch node allows to select one of its children for
  28 traversal instead of all of them (as for the other nodes).
  29 The Switch grouping node traverses zero, all or one of the children.
  30
  31 \section NCGroupsTransform Transform
  32
  33 The Transform node is a grouping node that defines a coordinate system for its
  34 children that is relative to the coordinate systems of its ancestors.
  35 A Transform Core is the basic means of moving objects around the scene. It
  36 keeps a single Matrix that is applied to all its children.
  37
  38 \section NCGroupsComponentTransform ComponentTransform
  39
  40 A ComponentTransform is close to a Transform, but the transformation is
  41 defined in an easier to use way, the same way it is done in systems like
  42 OpenInventor or VRML:
  43
  44 The center field specifies a translation offset from the origin of the local coordinate system (0,0,0).
  45 The rotation field specifies a rotation of the coordinate system.
  46 The scale field specifies a non-uniform scale of the coordinate system.
  47 scale values shall be greater than zero.
  48 The scaleOrientation specifies a rotation of the coordinate system before
  49 the scale (to specify scales in arbitrary orientations).
  50 The scaleOrientation applies only to the scale operation.
  51 The translation field specifies a translation to the coordinate system.
  52
  53 Given a 3-dimensional point P and Transform node, P is transformed into point P' in its parent's
  54 coordinate system by a series of intermediate transformations. In matrix transformation notation,
  55 where C (center), SR (scaleOrientation), T (translation), R (rotation), and S (scale)
  56 are the equivalent transformation matrices,
  57
  58 P' = T × C × R × SR × S × -SR × -C × P
  59
  60 \section NCGroupsDistanceLOD DistanceLOD
  61
  62 Levels of Detail are a simple way of increasing rendering performance. The
  63 basic idea is to have a number of differently detailed versions of an object
  64 and use low-res versions for objects that are far away.
  65
  66 A DistanceLOD is the simplest version, which switches versions based on
  67 distance to the viewer. The children is selected based on the
  68 center and range settings.
  69
  70 The center field is a translation offset in the local coordinate system that
  71 specifies the centre of the LOD node for distance calculations.
  72
  73 The number of children shall exceed the number of values in the range field by
  74 one (i.e., N+1 children for N range values). The range field contains
  75 monotonic increasing values that shall be greater than 0. In order to
  76 calculate which level to display, the distance is calculated from the viewer's
  77 location, transformed into the local coordinate system of the LOD node
  78 (including any scaling transformations), to the center point of the LOD node.
  79
  80 \image html distanceLOD.png "DistanceLOD example"
  81 \image latex distanceLOD.eps "DistanceLOD example" width=8cm
  82
  83 \section NCGroupsLights Lights
  84
  85 A Light defines a source of light in the scene. Generally, two types of
  86 information are of interest: The position of the light source (geometry), and
  87 what elements of the scene are lit (semantics).
  88
  89 Using the position of the light in the graph for geometry allows moving the
  90 Light just like any other node, by putting it below a osg::Transform Node and
  91 changing the transformation. This consistency also simplifies attaching Lights
  92 to moving parts in the scene: just put them below the same Transform and they
  93 will move with the object.
  94
  95 The semantic interpretation also makes sense, it lets you restrict the
  96 influence area of the light to a subgraph of the scene. This can be used for
  97 efficiency, as every active light increases the amount of calculations
  98 necessary per vertex, even if the light doesn't influence the vertex, because
  99 it is too far away. It can also be used to overcome the restrictions on the
 100 number of lights. OpenSG currently only allows 8 concurrently active lights.
 101
 102 It is also not difficult to imagine situations where both interpretations are
 103 necessary at the same time. Take for example a car driving through a night
 104 scene. You'd want to headlights to be fixed to the car and move together with
 105 it. But at the same time they should light the houses you're driving by, and
 106 not the mountains in the distance.
 107
 108 Thus there should be a way to do both at the same time. OpenSG solves this by
 109 splitting the two tasks to two Nodes. The Light's Node is for the sematntic
 110 part, it defines which object are lit by the Light. FOr the geometrc part the
 111 Light keeps a SFNodePtr to a different Node, the so called beacon. The local
 112 coordinate system of the beacon provides the reference coordinate system for
 113 the light's position.
 114
 115 Thus the typical setup of an OpenSG scenegraph starts with a set of lights,
 116 which light the whole scene, followed by the actual geometry.
 117
 118 Tip: Using the beacon of the camera (see \ref PageSystemWindowCamera)
 119 as the beacon of a light source creates a headlight.
 120
 121 NOTE: Currently OpenSG does not implement the restricted influence area. All
 122 Light sources are global and light the whole scene. Expect that to change
 123 soon!
 124
 125 Every light is closely related to OpenGL's light specification. It has a
 126 diffuse, specular and ambient color. Additionally it can be switched on and
 127 off using the on field.
 128
 129 \subsection NCGroupsDirectionalLight DirectionalLight
 130
 131 The DirectionalLight just has a direction.
 132
 133 To use it as a headlight use
 134 (0,0,-1) as a direction. it is the computationally cheapest light source. Thus
 135 for the fastest lit rendering, just a single directional light source. The
 136 osg::SimpleSceneManager's headlight is a directional light source.
 137
 138 \subsection NCGroupsPointLight PointLight
 139
 140 The PointLight has a position to define its location. In addition, as it
 141 really is located in the scene, it has attenuation parameters to change the
 142 light's intensity depending on the distance to the light.
 143
 144 Point lights are more expesinve to compute than directional lights, but not
 145 quite as expesive as spot lights. If you need to see the localized effects of
 146 the light, a point light is a good compromise between speed and quality.
 147
 148 \subsection NCGroupsSpotLight SpotLight
 149
 150 The SpotLight adds a direction to the PointLight and a spotCutOff angle to
 151 define the area that's lit. To define the light intensity fallof within that
 152 area the spotExponent field is used.
 153
 154 Spot lights are very expensive to compute, use them sparingly.
 155
 156
 157 */