Doc/to_port/Material.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemMaterial Materials
   6     \ingroup GrpSystem
   7
   8 Materials define the surface properties of the geometry and abstract the actual
   9 implementation from the user.
  10
  11 See \ref PageSystemMaterial for a detailed description.
  12 */
  13
  14 /*! \page PageSystemMaterial Materials
  15
  16 \latexonly Starter:NewChapter \endlatexonly
  17
  18 Materials define the surface properties of the geometry. For the standard
  19 Phong lighting model that OpenGL uses these are ambient, diffuse and specular
  20 color as well as shininess. However, this is an area where extensions are
  21 added at an amazing pace. The purpose of materials is to add a level of
  22 abstraction and give the user an easy to use interface to define surface
  23 properties without having to worry about the details of realizing them (e.g.
  24 how to use multiple passes, when and how to calculate derived information like
  25 tangents and binormals etc.).
  26
  27 This area is quickly expanding, so what we have right now is just the
  28 beginning.
  29
  30 \ext To use a Material the geometry will call the Material's
  31 osg::Material::draw() method, which decides what to do. Right now all it can
  32 do is directly draw itself or pass itself to the Rendering Backend to be
  33 rendered later. To actually be used by the renderer Materials have a method to
  34 give out a osg::State to be used to render their associated geometry. For
  35 efficiency reasons this State should be kept ready to use in the Material and
  36 returned when needed.
  37
  38 This whole interface is a bit convoluted, unclear, can't handle all the cases
  39 that it should and thus will change pretty soon. Stay tuned.\endext
  40
  41
  42 \section PageSystemMaterialTypes Material types
  43
  44 \subsection PageSystemMaterialChunkMaterial ChunkMaterial
  45
  46 The osg::ChunkMaterial is a material that is just a collection of \ref
  47 StateChunk "osg::StateChunks". This allows adding and using new
  48 extensions in the form of state chunks pretty easily.
  49
  50 It is also the base class for the simple materials given below.
  51
  52 \subsection PageSystemMaterialSimpleMaterial SimpleMaterial
  53
  54 The osg::SimpleMaterial is a pretty direct mapping of the OpenGL light model.
  55 It has colors for ambient, diffuse, specular and emission properties, and a
  56 shininess value. In addition to that it has a transparency setting, ranging
  57 from 0 for opaque to 1 for fully transparent.
  58
  59 There are two other attributes in a SimpleMaterial that control the appearance
  60 of an object. One is the lit attribute, which defines if the material is
  61 influenced by light sources at all. If it isn't, the color is directly taken
  62 from the diffuseColor component and other color attributes are ignored.
  63
  64 The other attribute is the colorMaterial field, which defines how colors that
  65 are given in the geometry influence the lighting calculation. By default they
  66 replace the diffuse color only. Possible values are taken from the
  67 glColorMaterial() call, the most useful being GL_DIFFUSE_AND_SPECULAR. One
  68 possible value that is not used by glColorMaterial() is GL_NONE, which
  69 switches off the color material handling and thus ignores colors that are
  70 given in the geometry.
  71
  72 As SimpleMaterial is derived from osg::ChunkMaterial, other attributes can be
  73 added in the form of \ref StateChunk "StateChunks".
  74
  75 \subsection PageSystemMaterialTexturedSimpleMaterial TexturedSimpleMaterial
  76
  77 osg::SimpleTexturedMaterial is derived from osg::SimpleMaterial and adds a
  78 texture. The texture is defined by an image (see \ref PageSystemImage for details on
  79 how to define or load an image).
  80
  81 Additionally there are some parameters to define the behavior of a texture.
  82 magFilter and minFilter define how to scale the texture image up or down,
  83 legal values taken from glTexParameter(). The most useful ones are GL_NEAREST
  84 or GL_LINEAR for magFilter, and additionally GL_LINEAR_MIPMAP_LINEAR for
  85 minFilter.
  86
  87 envMode defines how a color from the texture is combined with a color from the
  88 lighting calculation. The default is GL_REPLACE which completely ignores the
  89 lighting color. Other useful values are GL_MODULATE, which just multiplies the
  90 two, and GL_DECAL, which interpolates between lighting and texture based on
  91 the texture's alpha channel.
  92
  93 Finally, a texture can be used as a spherical environment map to simulate a
  94 reflective object by setting the envMap field to true. Spherical environment
  95 maps need to display the image of a reflective sphere in the middle of the
  96 environment that is being reflected.
  97
  98 As TexturedSimpleMaterial is derived from osg::ChunkMaterial, other attributes
  99 can be added in the form of \ref StateChunk "StateChunks".
 100
 101 */