docs-mini/README.effects

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