From 4ddd8a89340bbe6e97cb04f6c7f08da034379f1f Mon Sep 17 00:00:00 2001 From: fredb Date: Sat, 27 Feb 2010 13:29:50 +0000 Subject: [PATCH] Fix line endings --- Docs/README.effects | 579 ++++++++++++++++++++++---------------------- 1 file changed, 287 insertions(+), 292 deletions(-) diff --git a/Docs/README.effects b/Docs/README.effects index 72ce18ba7..deba14e9f 100644 --- a/Docs/README.effects +++ b/Docs/README.effects @@ -1,292 +1,287 @@ -Effects -------- - -Effects describe the graphical appearance of 3d objects and scenery in -FlightGear. The main motivation for effects is to support OpenGL -shaders and to provide different implementations for graphics hardware -of varying capabilities. Effects are similar to DirectX effects files -and Ogre3D material scripts. - -An effect is a property list. The property list syntax is extended -with new "vec3d" and "vec4d" types to support common computer graphics -values. Effects are read from files with a ".eff" extension or can be -created on-the-fly by FlightGear at runtime. An effect consists of a -"parameters" section followed by "technique" descriptions. The -"parameters" section is a tree of values that describe, abstractly, -the graphical characteristics of objects that use the effect. Techniques -refer to these parameters and use them to set OpenGL state or to set -parameters for shader programs. The names of properties in the -parameter section can be whatever the effects author chooses, although -some standard parameters are set by FlightGear itself. On the other -hand, the properties in the techniques section are all defined by the -FlightGear. - -Techniques ----------- - -A technique can contain a predicate that describes the OpenGL -functionality required to support the technique. The first -technique with a valid predicate in the list of techniques is used -to set up the graphics state of the effect. A technique with no -predicate is always assumed to be valid. The predicate is written in a -little expression language that supports the following primitives: - -and, or, equal, less, less-equal -glversion - returns the version number of OpenGL -extension-supported - returns true if an OpenGL extension is supported -property - returns the boolean value of a property -shader-language - returns the version of GLSL supported, or 0 if there is none. - -The proper way to test whether to enable a shader-based technique is: - - - /sim/rendering/shader-effects - - 1.0 - - - - - - -A technique can consist of several passes. A pass is basically an Open -Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state -attributes will be accessable in techniques. State attributes -- that -is, technique properties that have children and are not just boolean -modes -- have an parameter which enables or disables the -attribute. In this way a technique can declare parameters it needs, -but not enable the attribute at all if it is not needed; the decision -can be based on a parameter in the parameters section of the -effect. For example, effects that support transparent and opaque -geometry could have as part of a technique: - - - blend/active - src-alpha - one-minus-src-alpha - - -So if the blend/active parameter is true blending will be activated -using the usual blending equation; otherwise blending is disabled. - -Values of Technique Attributes ------------------------------- - -Values are assigned to technique properties in several ways: - - * They can appear directly in the techniques section as a - constant. For example: - - ColorsTex - sampler-1d - < value type="int">2 - - * The name of a property in the parameters section can be - referenced using a "use" clause. For example, in the technique - section: - - material/ambient - - Then, in the parameters section of the effect: - - - 0.2 0.2 0.2 1.0 - - - - It's worth pointing out that the "material" property in a - technique specifies part of OpenGL's state, whereas "material" - in the parameters section is just a name, part of a - hierarchical namespace. - - * A property in the parameters section doesn't need to contain - a constant value; it can also contain a "use" property. Here - the value of the use clause is the name of a node in an - external property tree which will be used as the source of a - value. If the name begins with '/', the node is in - FlightGear's global property tree; otherwise, it is in a local - property tree, usually belonging to a model [NOT IMPLEMENTED - YET]. For example: - - /rendering/scene/chrome-light - - The type is determined by what is expected by the technique - attribute that will ultimately receive the value. [There is - no way to get vector values out of the main property system - yet; this will be fixed shortly.] Values that are declared - this way are dynamically updated if the property node - changes. - -OpenGL Attributes ------------------ - -The following attributes are currently implemented in techiques: -alpha-test - children: active, comparison, reference - Valid values for comparision: - never, less, equal, lequal, greater, notequal, gequal, - always - -blend - children: active, source, destination, source-rgb, - source-alpha, destination-rgb, destination-alpha - Each operand can have the following values: - dst-alpha, dst-color, one, one-minus-dst-alpha, - one-minus-dst-color, one-minus-src-alpha, - one-minus-src-color, src-alpha, src-alpha-saturate, - src-color, constant-color, one-minus-constant-color, - constant-alpha, one-minus-constant-alpha, zero - -cull-face - front, back, front-back - -lighting - true, false - -material - children: active, ambient, ambient-front, ambient-back, diffuse, - diffuse-front, diffuse-back, specular, specular-front, - specular-back, emissive, emissive-front, emissive-back, shininess, - shininess-front, shininess-back, color-mode - -polygon-mode - children: front, back - Valid values: - fill, line, point - -program - vertex-shader - fragment-shader - -render-bin - (OSG) children: bin-number, bin-name - -rendering-hint - (OSG) opaque, transparent - -shade-model - flat, smooth - -texture-unit - has several child properties: - unit - The number of an OpenGL texture unit - type - This is either an OpenGL texture type or the name of a - builtin texture. Currently supported OpenGL types are 1d, 2d, - 3d which have the following common parameters: - image (file name) - filter - mag-filter - wrap-s - wrap-t - wrap-r - The following built-in types are supported: - white - 1 pixel white texture - noise - a 3d noise texture - environment - mode - color -uniform - name - type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, - sampler-3d - -vertex-program-two-side - true, false - -vertex-program-point-size - true, false - -Inheritance ------------ - -One feature not fully illustrated in the sample below is that -effects can inherit from each other. The parent effect is listed in -the "inherits-from" form. The child effect's property tree is -overlaid over that of the parent. Nodes that have the same name and -property index -- set by the "n=" attribute in the property tag -- -are recursively merged. Leaf property nodes from the child have -precedence. This means that effects that inherit from the example -effect below could be very short, listing just new -parameters and adding nothing to the techniques section; -alternatively, a technique could be altered or customized in a -child, listing (for example) a different shader program. An example -showing inheritance Effects/crop.eff, which inherits some if its -values from Effects/terrain-default.eff. - -FlightGear directly uses effects inheritance to assign effects to 3D -models and terrain. As described below, at runtime small effects are -created that contain material and texture values in a "parameters" -section. These effects inherit from another effect which references -those parameters in its "techniques" section. The derived effect -overrides any default values that might be in the base effect's -parameters section. - -Default Effects in Terrain Materials and Models ---------------------------------------- - -Effects for terrain work in this way: for each material type in -materials.xml an effect is created that inherits from a single default -terrain effect, Effects/terrain-default.eff. The parameters section of -the effect is filled in using the ambient, diffuse, specular, -emissive, shininess, and transparent fields of the material. The -parameters image, filter, wrap-s, and wrap-t are also initialized from -the material xml. Seperate effects are created for each texture -variant of a material. - -Model effects are created by walking the OpenSceneGraph scene graph -for a model and replacing nodes (osg::Geode) that have state sets with -node that uses an effect instead. Again, a small effect is created -with parameters extracted from OSG objects; this effect inherits, by -default, from Effects/model-default.eff. A larger set of parameters is -created for model effects than for terrain because there is more -variation possible from the OSG model loaders than from the terrain -system. The parameters created are: - - * material active, ambient, diffuse, specular, emissive, - shininess, color mode - * blend active, source, destination - * shade-model - * cull-face - * rendering-hint - * texture type, image, filter, wrap-s, wrap-t - -Specifying Custom Effects -------------------------- - -You can specify the effects that will be used by FlightGear as the -base effect when it creates terrain and model effects. - -In the terrain materials.xml, an "effect" property specifies the name -of the model to use. - -In model .xml files, A richer syntax is supported. [TO BE DETERMINED] - -Material animations will be implemented by creating a new effect -that inherits from one in a model, overriding the parameters that -will be animated. - -Examples --------- - -The Effects directory contains the effects definitions; look there for -examples. Effects/crop.eff is a good example of a complex effect. - -Application ------------ - -To apply an effect to a model or part of a model use: - - - Effects/light-cone - Cone - - -where contains the path to the effect you want to apply. -The effect does not need the file extension. - -NOTE: - -Chrome, although now implemented as an effect, still retains the old method of application: - - - shader - chrome - glass_shader.png - windscreen - - -in order to maintain backward compatibility. - - - - - - +Effects +------- + +Effects describe the graphical appearance of 3d objects and scenery in +FlightGear. The main motivation for effects is to support OpenGL +shaders and to provide different implementations for graphics hardware +of varying capabilities. Effects are similar to DirectX effects files +and Ogre3D material scripts. + +An effect is a property list. The property list syntax is extended +with new "vec3d" and "vec4d" types to support common computer graphics +values. Effects are read from files with a ".eff" extension or can be +created on-the-fly by FlightGear at runtime. An effect consists of a +"parameters" section followed by "technique" descriptions. The +"parameters" section is a tree of values that describe, abstractly, +the graphical characteristics of objects that use the effect. Techniques +refer to these parameters and use them to set OpenGL state or to set +parameters for shader programs. The names of properties in the +parameter section can be whatever the effects author chooses, although +some standard parameters are set by FlightGear itself. On the other +hand, the properties in the techniques section are all defined by the +FlightGear. + +Techniques +---------- + +A technique can contain a predicate that describes the OpenGL +functionality required to support the technique. The first +technique with a valid predicate in the list of techniques is used +to set up the graphics state of the effect. A technique with no +predicate is always assumed to be valid. The predicate is written in a +little expression language that supports the following primitives: + +and, or, equal, less, less-equal +glversion - returns the version number of OpenGL +extension-supported - returns true if an OpenGL extension is supported +property - returns the boolean value of a property +shader-language - returns the version of GLSL supported, or 0 if there is none. + +The proper way to test whether to enable a shader-based technique is: + + + /sim/rendering/shader-effects + + 1.0 + + + + + + +A technique can consist of several passes. A pass is basically an Open +Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state +attributes will be accessable in techniques. State attributes -- that +is, technique properties that have children and are not just boolean +modes -- have an parameter which enables or disables the +attribute. In this way a technique can declare parameters it needs, +but not enable the attribute at all if it is not needed; the decision +can be based on a parameter in the parameters section of the +effect. For example, effects that support transparent and opaque +geometry could have as part of a technique: + + + blend/active + src-alpha + one-minus-src-alpha + + +So if the blend/active parameter is true blending will be activated +using the usual blending equation; otherwise blending is disabled. + +Values of Technique Attributes +------------------------------ + +Values are assigned to technique properties in several ways: + + * They can appear directly in the techniques section as a + constant. For example: + + ColorsTex + sampler-1d + < value type="int">2 + + * The name of a property in the parameters section can be + referenced using a "use" clause. For example, in the technique + section: + + material/ambient + + Then, in the parameters section of the effect: + + + 0.2 0.2 0.2 1.0 + + + + It's worth pointing out that the "material" property in a + technique specifies part of OpenGL's state, whereas "material" + in the parameters section is just a name, part of a + hierarchical namespace. + + * A property in the parameters section doesn't need to contain + a constant value; it can also contain a "use" property. Here + the value of the use clause is the name of a node in an + external property tree which will be used as the source of a + value. If the name begins with '/', the node is in + FlightGear's global property tree; otherwise, it is in a local + property tree, usually belonging to a model [NOT IMPLEMENTED + YET]. For example: + + /rendering/scene/chrome-light + + The type is determined by what is expected by the technique + attribute that will ultimately receive the value. [There is + no way to get vector values out of the main property system + yet; this will be fixed shortly.] Values that are declared + this way are dynamically updated if the property node + changes. + +OpenGL Attributes +----------------- + +The following attributes are currently implemented in techiques: +alpha-test - children: active, comparison, reference + Valid values for comparision: + never, less, equal, lequal, greater, notequal, gequal, + always + +blend - children: active, source, destination, source-rgb, + source-alpha, destination-rgb, destination-alpha + Each operand can have the following values: + dst-alpha, dst-color, one, one-minus-dst-alpha, + one-minus-dst-color, one-minus-src-alpha, + one-minus-src-color, src-alpha, src-alpha-saturate, + src-color, constant-color, one-minus-constant-color, + constant-alpha, one-minus-constant-alpha, zero + +cull-face - front, back, front-back + +lighting - true, false + +material - children: active, ambient, ambient-front, ambient-back, diffuse, + diffuse-front, diffuse-back, specular, specular-front, + specular-back, emissive, emissive-front, emissive-back, shininess, + shininess-front, shininess-back, color-mode + +polygon-mode - children: front, back + Valid values: + fill, line, point + +program + vertex-shader + fragment-shader + +render-bin - (OSG) children: bin-number, bin-name + +rendering-hint - (OSG) opaque, transparent + +shade-model - flat, smooth + +texture-unit - has several child properties: + unit - The number of an OpenGL texture unit + type - This is either an OpenGL texture type or the name of a + builtin texture. Currently supported OpenGL types are 1d, 2d, + 3d which have the following common parameters: + image (file name) + filter + mag-filter + wrap-s + wrap-t + wrap-r + The following built-in types are supported: + white - 1 pixel white texture + noise - a 3d noise texture + environment + mode + color +uniform + name + type - float, float-vec3, float-vec4, sampler-1d, sampler-2d, + sampler-3d + +vertex-program-two-side - true, false + +vertex-program-point-size - true, false + +Inheritance +----------- + +One feature not fully illustrated in the sample below is that +effects can inherit from each other. The parent effect is listed in +the "inherits-from" form. The child effect's property tree is +overlaid over that of the parent. Nodes that have the same name and +property index -- set by the "n=" attribute in the property tag -- +are recursively merged. Leaf property nodes from the child have +precedence. This means that effects that inherit from the example +effect below could be very short, listing just new +parameters and adding nothing to the techniques section; +alternatively, a technique could be altered or customized in a +child, listing (for example) a different shader program. An example +showing inheritance Effects/crop.eff, which inherits some if its +values from Effects/terrain-default.eff. + +FlightGear directly uses effects inheritance to assign effects to 3D +models and terrain. As described below, at runtime small effects are +created that contain material and texture values in a "parameters" +section. These effects inherit from another effect which references +those parameters in its "techniques" section. The derived effect +overrides any default values that might be in the base effect's +parameters section. + +Default Effects in Terrain Materials and Models +--------------------------------------- + +Effects for terrain work in this way: for each material type in +materials.xml an effect is created that inherits from a single default +terrain effect, Effects/terrain-default.eff. The parameters section of +the effect is filled in using the ambient, diffuse, specular, +emissive, shininess, and transparent fields of the material. The +parameters image, filter, wrap-s, and wrap-t are also initialized from +the material xml. Seperate effects are created for each texture +variant of a material. + +Model effects are created by walking the OpenSceneGraph scene graph +for a model and replacing nodes (osg::Geode) that have state sets with +node that uses an effect instead. Again, a small effect is created +with parameters extracted from OSG objects; this effect inherits, by +default, from Effects/model-default.eff. A larger set of parameters is +created for model effects than for terrain because there is more +variation possible from the OSG model loaders than from the terrain +system. The parameters created are: + + * material active, ambient, diffuse, specular, emissive, + shininess, color mode + * blend active, source, destination + * shade-model + * cull-face + * rendering-hint + * texture type, image, filter, wrap-s, wrap-t + +Specifying Custom Effects +------------------------- + +You can specify the effects that will be used by FlightGear as the +base effect when it creates terrain and model effects. + +In the terrain materials.xml, an "effect" property specifies the name +of the model to use. + +In model .xml files, A richer syntax is supported. [TO BE DETERMINED] + +Material animations will be implemented by creating a new effect +that inherits from one in a model, overriding the parameters that +will be animated. + +Examples +-------- + +The Effects directory contains the effects definitions; look there for +examples. Effects/crop.eff is a good example of a complex effect. + +Application +----------- + +To apply an effect to a model or part of a model use: + + + Effects/light-cone + Cone + + +where contains the path to the effect you want to apply. +The effect does not need the file extension. + +NOTE: + +Chrome, although now implemented as an effect, still retains the old method of application: + + + shader + chrome + glass_shader.png + windscreen + + +in order to maintain backward compatibility. +