Doc/to_port/Action.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemAction Action
   6     \ingroup GrpSystem
   7
   8 The Actions are the active components that traverse the tree of nodes and
   9 perform function (or rather functors) on them.
  10
  11 */
  12
  13 /*! \page PageSystemAction Action
  14
  15 \latexonly Starter:NewChapter \endlatexonly
  16
  17 Creating the scene-graph is just the first step, and not really useful in
  18 itself. Something needs to be done with it. Actions on the graph usually take
  19 the form of a traversal which goes through the nodes one by one and calls an
  20 appropriate action for each one on the way.
  21
  22 These are called Actions in OpenSG, and there are a number of predefined
  23 actions:
  24
  25 \li Render
  26
  27 \li Intersect
  28
  29
  30 \section PageSystemActionUsage Usage
  31
  32 Actions use the same syntax for creating as actions that FieldContainers use,
  33 as they also use a prototype for that. Thus you need to call
  34 ActionType::create to get a new one. They are not FieldContainers, though, so
  35 simple pointers are OK.
  36
  37 To execute an action on a graph you apply it to the graph
  38 (action->apply(graph);) or to a list of nodes
  39 (action->apply(vector<NodePtr>::iterator begin, vector<NodePtr>::iterator
  40 end);).
  41
  42 \section PageSystemActionRenderAction RenderAction
  43
  44 RenderAction is the primary means of transforming the scene-graph into an
  45 image. It does view volume culling and state sorting by building a draw tree.
  46 It also handles transparent objects by rendering them last and back to front
  47 sorted. Put simple it does what a decent scene-graph needs to do.
  48
  49 To use it just create one and pass it to the OpenSG Window object (see
  50 \ref PageSystemWindow).
  51
  52 It is possible to turn the view volume culling off using the
  53 setFrustumCulling() method. For debugging it is possible to turn the frustum
  54 update off (setAutoFrustum()) and to make the system render the tested
  55 bounding volumes (setVolumeDraw()).
  56
  57 \section PageSystemActionIntersectAction IntersectAction
  58
  59 IntersectAction is used for sending rays into the scene and retrieving the
  60 first object hit. Right now, intersection testing is not very optimized, which
  61 is OK for selecting an object, but probably too slow for programmatic use.
  62
  63 A ray is defined by a Line (see \ref osg::Line) and optionally a maximum
  64 distance. It can either be set at construction time or by setLine(). To test
  65 the ray for intersection, apply the action to the root of the possible
  66 intersection objects.
  67
  68 If the ray hits an object didHit() will return true. In that case, detailed
  69 info about what was hit and where can be accessed through getHitT(),
  70 getHitPoint(), getHitObject() and getHitTriangle().
  71
  72 \section PageSystemActionSimpleTraversal Simple Traversal
  73
  74 Actions are somewhat complicated to derive and, furthermore, they manage
  75 callback functors on a NodeCore basis. Sometimes it's easier to just define a
  76 function that is called for every node in a graph. That's what traverse() is
  77 for.
  78
  79 traverse() takes a NodePtr to define the graph and a functor to define the
  80 function to be called for every node as parameters. The functor just gets the
  81 traversed node as a parameter
  82
  83 \section PageSystemActionOwn Write your own action handler
  84
  85 Don't. Actions are being completely redesigned for 1.1 to become more flexible
  86 and clean. Use the available actions and try to stay with the traverse()
  87 function for now.
  88
  89 If you really need to do your own action take a look at IntersectAction, it
  90 shows what you need to implement. Talk to us before you do it, though, maybe
  91 the redesign is already usable so you can base your new stuff on that.
  92
  93 */