docs-mini/README.effects

   1 <?xml version="1.0" encoding="utf-8">
   2 <!--
   3    An effect consists of parameters and techniques. The "parameters"
   4    section of an effect is a tree of values that describe, abstractly,
   5    the graphical appearence of objects that use the effect. Techniques
   6    refer to these parameters and use them to set OpenGL state or to
   7    set parameters for shader programs. Parameters can be declared to
   8    have a dynamic variance, which means that if their value is changed
   9    the corresponding value in the technique will be changed too.
  10
  11    A technique can contain a predicate that describes the OpenGL
  12    functionality required to support the technique. The first
  13    technique with a valid predicate in the list of techniques is used
  14    to set up the graphics state of the effect. A technique with no
  15    predicate is always assumed to be valid.
  16
  17    A technique can consist of several passes, which are run in
  18    sequence.
  19
  20    One feature not fully illustrated in the sample below is that
  21    effects can inherit from each other. The parent effect is listed in
  22    the "inherits-from" form. The child effect's property tree is
  23    overlaid over that of the parent. This means that effects that
  24    inherit from the example "default effect" below could be very
  25    short, listing just new parameters and adding nothing to the
  26    techniques section; alternatively, a technique could be altered or
  27    customized in a child, listing (for example) a different shader
  28    program. Terrain materials work in this way: for each material type
  29    in materials.xml an effect is created that inherits from a single
  30    default terrain effect. The parameters section of the effect is
  31    filled in using the ambient, diffuse, etc. fields of the material.
  32
  33    Material animations will be implemented by creating a new effect
  34    that inherits from one in a model, overriding the parameters that
  35    will be animated.
  36
  37    Ultimately all OpenGL state will be setable in a technique. These
  38    attributes and modes are currently implemented:
  39    lighting - true, false
  40    shade-model - flat, smooth
  41    cull-face - front, back, front-back
  42    rendering-hint - (OSG) opaque, transparent
  43    render-bin - children: bin-number, bin-name
  44    material - children: ambient, ambient-front, ambient-back, diffuse,
  45    diffuse-front, diffuse-back, specular, specular-front,
  46    specular-back, emissive, emissive-front, emissive-back, shininess,
  47    shininess-front, shininess-back, color-mode
  48    blend - true, false
  49    alpha-test - true, false
  50    texture-unit -
  51         unit
  52         texture2d
  53                 image (file name)
  54                 filter
  55                 mag-filter
  56                 wrap-s
  57                 wrap-t
  58                 wrap-r
  59         environment
  60                 mode
  61                 color
  62    program
  63         vertex-shader
  64         fragment-shader
  65    uniform
  66         name
  67         type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
  68                sampler-3d
  69    polygon-mode
  70         front - fill, line, point
  71         back - fill, line, point
  72   -->
  73 <PropertyList>
  74   <effect>
  75     <name>city</name>
  76     <!-- <inherits-from>another-effect</inherits-from> -->
  77     <parameters>
  78       <material>
  79         <ambient type="vec4d">
  80           0.0 0.0 0.0 1.0
  81         </ambient>
  82         <diffuse type="vec4d">
  83           .5 .5 .5 1.0
  84         </diffuse>
  85         <specular type="vec4d">
  86           0.3 0.3 0.3 1.0
  87         </specular>
  88         <emissive type="vec4d" variance="dynamic">
  89           0.0 0.0 0.0 1.0
  90         </emissive>
  91         <shininess>1.2</shininess>
  92       </material>
  93       <texture n="0">
  94         <texture2d>
  95           <image>city.png</image>
  96           <filter>linear-mipmap-linear</filter>
  97           <!-- also repeat -->
  98           <wrap-s>clamp</wrap-s>
  99           <wrap-t>clamp-to-edge</wrap-t>
 100           <!--
 101              <wrap-r>clamp-to-border</wrap-r>
 102              -->
 103           <!-- float, signed-integer, integer -->
 104           <internal-format>normalized</internal-format>
 105         </texture2d>
 106       </texture>
 107       <texture n="1">
 108         <texture2d>
 109           <image>detail.png</image>
 110           <filter>linear-mipmap-linear</filter>
 111           <!-- also repeat -->
 112           <wrap-s>clamp</wrap-s>
 113           <wrap-t>clamp-to-edge</wrap-t>
 114           <!--
 115              <wrap-r>clamp-to-border</wrap-r>
 116              -->
 117           <!-- float, signed-integer, integer -->
 118           <internal-format>normalized</internal-format>
 119         </texture2d>
 120       </texture>
 121       <bump-height type="double">.05</bump-height>
 122       <pattern-rotation type="vec4d">0 0 1 1.5708</pattern-rotation>
 123     </parameters>
 124     <technique>
 125       <predicate>
 126         <!-- This is the general way to test for shader support -->
 127         <or>
 128           <less-equal>
 129             <value type="float">2.0</value>
 130             <glversion/>
 131           </less-equal>
 132           <and>
 133             <extension-supported>GL_ARB_shader_objects</extension-supported>
 134             <extension-supported>GL_ARB_shading_language_100</extension-supported>
 135             <extension-supported>GL_ARB_vertex_shader</extension-supported>
 136             <extension-supported>GL_ARB_fragment_shader</extension-supported>
 137           </and>
 138         </or>
 139       </predicate>
 140       <pass>
 141         <lighting>true</lighting>
 142         <material>
 143           <ambient><use>material/ambient</use></ambient>
 144           <diffuse><use>material/diffuse</use></diffuse>
 145           <specular><use>material/specular</use></specular>
 146           <shininess><use>material/shininess</use></shininess>
 147         </material>
 148         <texture-unit>
 149           <texture2d><use>texture[0]/texture2d</use></texture2d>
 150         </texture-unit>
 151         <texture-unit>
 152           <texture2d><use>texture[1]/texture2d</use></texture2d>
 153         </texture-unit>
 154           <uniform>
 155             <name>bumpHeight</name>
 156             <type>float</type>
 157             <use>bump-height</use>
 158           </uniform>
 159           <uniform>
 160             <name>patternRotation</name>
 161             <type>float-vec4</type>
 162             <use>pattern-rotation</use>
 163           </uniform>
 164           <uniform>
 165             <name>baseTexture</name>
 166             <type>sampler-2d</type>
 167             <value>0</value>
 168           </uniform>
 169           <uniform>
 170             <name>detailTexture</name>
 171             <type>sampler-2d</type>
 172             <value>1</value>
 173           </uniform>
 174         <shader-program>
 175           <!-- These two vertex shaders are linked together -->
 176           <vertex-shader>
 177             "Shaders/util.vert"
 178           </vertex-shader>
 179           <vertex-shader>
 180             "Shaders/foo.vert"
 181           </vertex-shader>
 182           <fragment-shader>
 183             "Shaders/foo.frag"
 184           </fragment-shader>
 185         </shader-program>
 186       </pass>
 187     </technique>
 188     <!-- This  technique is always valid -->
 189     <technique>
 190       <pass>
 191         <lighting>true</lighting>
 192         <material>
 193           <ambient><use>material/ambient</use></ambient>
 194           <diffuse><use>material/diffuse</use></diffuse>
 195           <specular><use>material/specular</use></specular>
 196         </material>
 197         <texture-unit>
 198           <texture2d><use>texture[0]/texture2d</use></texture2d>
 199         </texture-unit>
 200       </pass>
 201     </technique>
 202   </effect>
 203 </PropertyList>