Doc/to_port/DrawablesParticles.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemNodeCoresDrawablesParticles Particles
   6     \ingroup GrpSystemNodeCoresDrawables
   7
   8 Particles are used for large numbers of simple, similar geometries.
   9
  10 See \ref PageSystemParticles for a description.
  11
  12 */
  13
  14 /*! \page PageSystemParticles Particles
  15
  16 The main idea of particles is to give a way of easily rendering large numbers
  17 of simple geometric objects. Particles are mostly used together with partially
  18 transparent textures to simulate fuzzy objects, but other uses are possible,
  19 e.g. molecules as stick-and-sphere models, stars or arrows for flow-field
  20 visualisations.
  21
  22 The Particles core can display different styles of particles and keeps all the
  23 data needed to do all of them. Not every style uses all the data, and using
  24 simpler setups can result in vastly improved performance\ext (if it doesn't, add a
  25 fast path to Particles::findDrawer ;) \endext.
  26
  27 The supported styles are:
  28  - Points
  29  - Lines
  30  - ViewDirQuads
  31  - Arrows
  32  - ViewerArrows
  33
  34 The available attributes are:
  35
  36  - Positions
  37  - secPositions
  38  - Colors
  39  - Normals
  40  - Sizes
  41  - textureZs
  42  - Indices
  43
  44 The first 4 are realized similarly to the Geometry Properties, to allow
  45 unified manipulation of data and sharing with geometry nodes. They can handle
  46 the same data formats the geometry can handle.
  47
  48 The only attribute every particle needs is the position. Some styles need
  49 other attributes, too, but most are optional. Colors, Normals, Sizes and
  50 textureZs can either be left empty, have a single element or have as many
  51 elements as there are positions. If only a single element is given, it is used
  52 by all particles, otherwise every particle has its own element.
  53
  54 The different types interpret the data as follows:
  55
  56 osg::Particles::ModeE::Points are rendered as simple GL_POINTS. Points use the
  57 positions, colors and textureZs attributes. A single size can (and should!) be
  58 given, but size per particle is not supported (yet). \dev The problem is that
  59 to be efficient it is necessary to sort the points by size and minimize the
  60 state changes. That's just not done yet. \enddev
  61
  62 osg::Particles::ModeE::Lines are two-point lines between a position and the
  63 corresponding secPosition, i.e. there have to be as many positions as
  64 secPositions. Colors and texture coordinates are used, too. A single size can
  65 (and should!) be given, but width per line is not supported (yet). \dev Same
  66 reason as for the points. \enddev
  67
  68 osg::Particles::ModeE::ViewDirQuads draw a single quad at the given position
  69 with the given size, color and texture Z. Only the X component of the size is
  70 used, and the given texture is used to fill the quad totally. The orientation
  71 of the quad is chosen to be parallel to the viewing direction, i.e. particles
  72 that are to the side of the viewer will be seen as a line.
  73
  74 osg::Particles::ModeE::ViewerQuads use just the same parameters as
  75 ViewDirQuads, but the particles are oriented to turn towards the viewer
  76 position, i.e. they always face the viewer, no matter where they are.
  77
  78 osg::Particles::ModeE::Arrows draws simple flat arrows. The coordinate system
  79 of the arrows is defined by the position, the secondary position and the
  80 normal. The tip of the arrow is at the position, the axis of the arrow points
  81 to the secondary position and the it is perpendicular to the normal. There
  82 need to be positions and secondary positions for every arrow, a single normal
  83 is possible, or a separate normal for every arrow.
  84
  85 osg::Particles::ModeE::ShaderQuads are designed to be rendered by a shader.
  86 The Particles core only supplies the data but does not try to do any kind of
  87 transformation on it, that's left to the shader. The data is passed to the
  88 shader as follows: the particle's position as texture coordinate 1, the
  89 secondary position as 2, the size as 3. Color and normal just use the regular
  90 OpenGL attributes. The vertices of the quad are fixed at (-.5,-.5), (.5,-.5),
  91 (.5,.5) and (-.5,.5), the texture coordinates 0 at (0,0), (1,0), (1,1) and
  92 (0,1). If set, the textureZs of the particles are set in the texture
  93 coordinate 0.
  94
  95 osg::Particles::ModeE::ShaderStrips are similar to the ShaderQuads. They also
  96 render a rectangle between (-.5,-.5) and (.5,.5), but they split it up into
  97 multiple slices, the number of slices is set by the z coordinate of the size
  98 attribute. For example setting size[2] to 2 would render two quads, with
  99 vertices (-.5,-.5), (.5,-.5), (.5,0), (-.5,0) and  (-.5,0), (.5,0), (.5,.5),
 100 (-.5,.5) (and corresponsing texture coordinates).
 101
 102 There is also a single material that is used to draw the particles, and an
 103 attribute to change the draw order of the particles.
 104
 105 \ext
 106 To extend the particles nodecore for rendering new things, do the following: XXX
 107 \endext
 108 */