Effect framework: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Created page WIP)
 
m (syntax for xml)
Line 48: Line 48:
To apply an effect to a model or part of a model use:
To apply an effect to a model or part of a model use:


<syntaxhighlight lang="xml">
<effect>
<effect>
<inherits-from>Effects/light-cone</inherits-from>
<inherits-from>Effects/light-cone</inherits-from>
<object-name>Cone</object-name>
<object-name>Cone</object-name>
</effect>
</effect>
</syntaxhighlight>


where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
Line 60: Line 62:
Chrome, although now implemented as an effect, still retains the old method of application:
Chrome, although now implemented as an effect, still retains the old method of application:


<syntaxhighlight lang="xml">
<animation>
<animation>
<type>shader</type>
<type>shader</type>
Line 66: Line 69:
<object-name>windscreen</object-name>
<object-name>windscreen</object-name>
</animation>
</animation>
</syntaxhighlight>


in order to maintain backward compatibility.
in order to maintain backward compatibility.
Line 185: Line 189:
the 'generate' clause is present in the effect file. Exemple :
the 'generate' clause is present in the effect file. Exemple :


<syntaxhighlight lang="xml">
<generate>
<generate>
<tangent type="int">6</tangent>
<tangent type="int">6</tangent>
Line 190: Line 195:
<normal type="int">8</normal>
<normal type="int">8</normal>
</generate>
</generate>
</syntaxhighlight>


Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
Line 200: Line 206:
be bound to an attribute in the program clause, like this :
be bound to an attribute in the program clause, like this :


<syntaxhighlight lang="xml">
<program>
<program>
<vertex-shader>my_vertex_shader</vertex-shader>
<vertex-shader>my_vertex_shader</vertex-shader>
Line 211: Line 218:
</attribute>
</attribute>
</program>
</program>
</syntaxhighlight>


attribute names are whatever the shader use. The index is the one  
attribute names are whatever the shader use. The index is the one  

Revision as of 04:53, 1 September 2019

The effect framework as per version 2019.1

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:

	<effect>
		<inherits-from>Effects/light-cone</inherits-from>
		<object-name>Cone</object-name>
	</effect>

where <inherits-from> </inherits-from> 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:

	<animation>
			<type>shader</type>
			<shader>chrome</shader>
			<texture>glass_shader.png</texture>
			<object-name>windscreen</object-name>
	</animation>

in order to maintain backward compatibility.

The xml tags of an effect

name

The name of the effect

inherits-from

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.

Parameters

Custom parameters that controls the effect.

Technique

A certain way of rendering this effect. Different pipelines typically have their own techniques.

predicate

Condition for this technique to be used. If this fails it will try the next technique in the effect.

pass

What is passed to the shaders/OSG. (Not sure, but think multiple passes are possible.)

lighting

true or 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

blend

Children: active, source, destination, source-rgb, source-alpha, destination-rgb, destination-alpha

Children 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

shade-model

flat or smooth

cull-face

front, back, front-back, off

rendering-hint

Sent to OSG.

default, opaque, transparent

texture-unit

vertex-program-two-side

true or false

vertex-program-point-size

true, false

uniform

Data accessible by shaders.

name
type

bool, int, float, float-vec3, float-vec4, sampler-1d, sampler-2d, sampler-3d, sampler-1d-shadow, sampler-2d-shadow, sampler-cube

alpha-test

active

true, false

comparison

never, less, equal, lequal, greater, notequal, gequal, always

reference

?

render-bin

Sent to OSG.

bin-number
bin-name

RenderBin, DepthSortedBin

program

vertex-shader geometry-shader fragment-shader attribute geometry-vertices-out: integer, max number of vertices emitted by geometry shader geometry-input-type - points, lines, lines-adjacency, triangles, triangles-adjacency geometry-output-type - points, line-strip, triangle-strip

Generate

Often shader effects need tangent vectors to work properly. These tangent vectors, usually called tangent and binormal, are computed on the CPU and given to the shader as vertex attributes. These vectors are computed on demand on the geometry using the effect if the 'generate' clause is present in the effect file. Exemple :

	<generate>
		<tangent type="int">6</tangent>
		<binormal type="int">7</binormal>
		<normal type="int">8</normal>
	</generate>

Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'. The integer value of these subnode is the index of the attribute that will hold the value of the vec3 vector.

The generate clause is located under PropertyList in the xml file.

In order to be available for the vertex shader, these data should be bound to an attribute in the program clause, like this :

	<program>
		<vertex-shader>my_vertex_shader</vertex-shader>
		<attribute>
			<name>my_tangent_attribute</name>
			<index>6</index>
		</attribute>
		<attribute>
			<name>my_binormal_attribute</name>
			<index>7</index>
		</attribute>
	</program>

attribute names are whatever the shader use. The index is the one declared in the 'generate' clause. So because generate/tangent has value 6 and my_tangent_attribute has index 6, my_tangent_attribute holds the tangent value for the vertex.