FlightGear wiki - User contributions [en]

Project Rembrandt

2012-05-17T19:04:53Z

Mcginnly: /* Caveats */ grmr

{{WIP}}
== Why this name ? ==
[http://en.wikipedia.org/wiki/Rembrandt Rembrandt] was a dutch painter living in the 17th century, famous as one of the master of [http://en.wikipedia.org/wiki/Chiaroscuro chiaroscuro].

This project is about changing the way [[FlightGear]] renders lights, [[shadows]] and shades, and aims at making Rembrandt painting style possible in FG.

== What is it ? ==
The idea driving the project is to implement [http://en.wikipedia.org/wiki/Deferred_shading deferred rendering] inside FlightGear.
From the beginning FlightGear had a forward renderer that tries to render all properties of an object in one pass (shading, lighting, fog, ...), making it difficult to render more sophisticated shading
(see the [[FlightGear Newsletter December 2011#Shaders|'Uber-shader']]) because one has to take into account all aspects of the [http://www.wired.com/magazine/2010/07/st_equation_3danimation/ rendering equation].

[[Image:project_rembrandt_1.png|thumb|300px|Main view with the content of buffers displayed at corners]]
On the contrary, deferred rendering is about separating operations in simplified stages and collecting the intermediary results in hidden buffers that can be used by the next stage.

;First stage is the Geometry Stage :
: we render all the scene into 4 textures, using multi render targets, to do it in one pass: one for the depth buffer, one for the normals (lower left of the image), one for the diffuse colors (lower right) and one for the specular colors (upper right).

;Next stage is the Shadow Stage :
: we render the scene again into a depth texture from the point of view of the lights. There will be one texture for every light casting shadows.

;Then comes the Lighting Stage, with several substages :
:*<u>Sky pass</u>: the sky is first drawn using classical method.
:*<u>Ambient pass</u>: the diffuse buffer is modulated with the ambient color of the scene and is drawn as a screen-aligned textured quad
:*<u>Sunlight pass</u>: a second screen aligned quad is drawn and a shader computes the view position of every pixel to compute its diffuse and specular color, using the normal stored in the first stage. The resulting color is blended with the previous pass. Shadows are computed here by comparing the position of the pixel with the position of the light occluder stored in the shadow map.
:*<u>Additional light pass</u>: the scene graph will be traversed another time to display light volumes (cone or frusta for spot lights, sphere for omni-directional lights) and their shader will add the light contributed by the source only on pixels receiving light.
:*<u>Fog pass</u>: a new screen aligned quad is draw and the position of the pixel is computed to evaluate the amount of fog the pixel has. The fog color is blended with the result of the previous stage.
:*<u>Transparent objects pass</u>: transparent objects (and clouds) are finally rendered using classical method.

:All lighting computations are accumulated in a single buffer that will be used for the last stage, in addition of the one computed by the Geometry stage.

;In the end, the Display Stage, with optional Post-Processing effect :
:The results of the previous buffers are pushed to the main framebuffer to be displayed, optionally modified to show Glow, Motion blur, HDR, redout or blackout, screen-space ambient occlusion, anti-aliasing, etc...

In FG, we end the rendering pipeline by displaying the [[Menubar|GUI]] and the [[HUD]].

All these stages are more precisely described if this [http://bat710.univ-lyon1.fr/~jciehl/Public/educ/GAMA/2007/Deferred_Shading_Tutorial_SBGAMES2005.pdf tutorial] that is the basis of the current code, with some addition and modifications.

== Caveats ==
Deferred rendering is not able to display transparency. For the moment, clouds are renderer separately and should be lit and shaded by their own. Transparent surfaces are alpha-tested and not blended. They would have to be drawn in their own bin over the composited image.

It also don't fit with depth partitioning because the depth buffer should be kept to retain the view space position, so for the moment, z-fighting is quite visible. Depth partitioning with non overlapping depth range might be the solution and should be experimented at one point.

The glow pass can make certain MFD (that use emissive color) unreadable because blurred. Should be treated as transparent.

== Implementation ==
=== Repositories ===
The code is in the main branch of the [[FlightGear and Git|official repository]]. Any other location is not maintained anymore.

=== Rendering of transparent surfaces ===
[[Image:project_rembrandt_5.png|thumb|300px|Transparent surfaces drawn after opaque objects]]
Transparent surfaces are detected by OSG loader plugins and their state set receive the TRANSPARENT_BIN rendering hint. In the culling pass, the cull visitor orders transparent surfaces in transparent bin. In a cull callback attached to the Geometry camera, after the scenegraph traversal, the transparent bins are removed from the render stage and saved in a temporary collection. In a cull callback attached to the Lighting camera, after the scenegraph traversal, the transparent bins saved at the previous stage, are added to the render stage of the Lighting camera with a high order num. That way, the transparent surface are drawn on top of the scene lighted from the Gbuffer.

=== Memory consumption ===
For each camera defined in the camera group, there is a separate shadow map, so the video memory usage is :
* G-buffer and Lighting buffer: 20 bytes per pixel. For an HD screen (1920x1080) memory requirement is 40 Mb
* Shadow map: 3 x shadow_map_size x shadow_map_size bytes (if size is 8192, whole map size is 192 Mb
Not counting textures, display list or vertex buffers for models and terrain

3 HD screens require 120 Mb of memory for the buffers (shadow excluded), you're asking 3x8192x8192x3 = 576 Mb (megabytes) of memory for the shadows alone.

If you are seeing error messages during startup or FlightGear doesn't start up properly, it's probably because you don't have enough free video memory. Reduce the size of the shadow map in preferences.xml by locating

<syntaxhighlight lang="xml">
<map-size type="int">8192</map-size>
</syntaxhighlight>

And put 4096 or 2048 instead.
You can also use a startup parameter: --prop:/sim/rendering/shadows/map-size=2048

=== Configurable pipeline ===

The Rembrandt renderer uses an XML file to setup its pipeline for each viewport described in the camera group. This file describes the way the intermediary buffers are setup and how the different rendering stages are sequenced. The general outline of a pipeline file is as follow :

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<PropertyList>

<buffer>

</buffer>
<buffer>

</buffer>


<stage>

</stage>
<stage>

</stage>
</PropertyList>
</syntaxhighlight>

==== Buffers ====
A buffer is a texture used as a storage area in the GPU. It's size is usually a multiple of the screen size, but fixed size is supported (typical for shadow map). The description of a buffer is described below :

<syntaxhighlight lang="xml">
<buffer>
<name>buffer-name</name>
<internal-format>rgba8</internal-format> 
<source-format>rgba</source-format> 
<source-type>unsigned-byte</source-type> 
<width>screen</width> 
<height>screen</height> 
<scale-factor>1.0</scale-factor>
<wrap-mode>clamp-to-border</wrap-mode> 

<shadow-comparison>true</shadow-comparison>

<condition>

</condition>
</buffer>
</syntaxhighlight>

==== Stages ====
A stage is an unit of rendering to a group of buffer. Most stages are predefined and their type is not free. When a type is not specified, the name is used. Stage types are :
{| class="wikitable"
!align="left"| Stage type
!align="left"| Purpose
|-
|geometry
|The geometry stage initialize most of the buffers and works on the real objects and geometry. Transparent objects are set aside and will be used untouched in the lighting stage. Other opaque geometry is rendered with the standard effects that do the hard work to put sensible data in the buffers.
|-
|shadow
|In this stage, the geometry is rendered in the normal map from the perspective of the sun.
|-
|lighting
|This stage uses the buffers filled by the previous stages to light every pixel of the scene. The result is rendered in another buffer to allow post effects.
|-
|fullscreen
|Stages of this type are used to alter the whole scene or transform data from a particular buffer.
|-
|display
|Final rendering of the scene to the screen or the texture defined in the camera group.
|}

A stage description is outlined below :
<syntaxhighlight lang="xml">
<stage>
<name>stage-name</name>
<type>stage-type</type> 
<order-num>-1</order-num>
<effect>Effects/fullscreen-effect</effect> 
<needs-du-dv>true</needs-du-dv> 
<scale-factor>0.25</scale-factor> 


<condition>

</condition>

<attachment>

</attachment>
<attachment>

</attachment>


<pass>

</pass>
<pass>

</pass>
</stage>
</syntaxhighlight>
Stages render in buffers (except for the display stage). Attachments describe which buffers are affected by each stage.

===== Attachments =====
Attachment describe bindings between buffer and attachment point :
<syntaxhighlight lang="xml">
<attachment>
<component>color0</component> 
<buffer>buffer-name</buffer>

<condition>

</condition>
</attachment>
</syntaxhighlight>

===== Passes =====
Passes are only available in the <tt>lighting</tt> stage. Three kind of stage are allowed :

{| class="wikitable"
!align="left"| Pass type
!align="left"| Purpose
|-
|sky-clouds
|Renders the skydome, sun, moon, planet, stars and clouds
|-
|lights
|Renders additional spot and point lights
|-
|fullscreen
|Fullscreen pass analog to a fullscreen stage except that it renders in the buffers attached to the lighting stage
|}
A pass is defined like below :
<syntaxhighlight lang="xml">
<pass>
<name>pass-name</name>
<type>pass-type</type> 
<order-num>-1</order-num>
<effect>Effects/fullscreen-effect</effect> 


<condition>

</condition>
</pass>
</syntaxhighlight>

A typical lighting stage is a succession of 5 passes :
# <tt>sky-clouds</tt> pass
# <tt>fullscreen</tt> pass for ambient light
# <tt>fullscreen</tt> pass for sun light (and shadows)
# <tt>lights</tt> pass
# <tt>fullscreen</tt> pass for fog

Each effect attached to the fullscreen passes define the way blending is done between the pass and the previous accumulation of render.

== Running Flightgear with Rembrandt ==

The Rembrandt renderer is now integrated in the main repository but needs to be enabled to run. Use the <tt>--enable-rembrandt</tt> option to start Flightgear with this new renderer.

Rembrandt is quite demanding in GPU resources and may fail to run with the default options. The more frequent symptom is an OSG message in the console :

RenderStage::runCameraSetUp(), FBO setup failed, FBO status= 0x8cd6
Warning: RenderStage::runCameraSetUp(State&) Pbuffer does not support multiple color outputs.

Some card also exhibit messages like this :

glLinkProgram "" FAILED
Program "" infolog:
Fragment info
-------------
0(37) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(36) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(35) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(34) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable

There is a number of additional options that can help to avoid these problems :

{| class="wikitable"
|<tt>--prop:/sim/rendering/rembrandt/use-color-for-depth=true</tt>
|Some old NVidia cards, such as 7600GT, don't give enough resolution for depth and that result in "fog curtains" at few meters from the viewer. One trick is to encode depth in another texture and get the proper value afterward. This option enables that.
|-
|<tt>--prop:/sim/rendering/shadows/enabled=false</tt>
|Disable shadows altogether. This setting is changeable at runtime in the rendering option dialog.
|-
|<tt>--prop:/sim/rendering/shadows/num-cascades=1</tt>
|Avoid the "error C6013" message on old cards at the cost of resolution in the cockpit. Set <tt>/sim/rendering/shadows/cascade-far-m[0]</tt> to change the shadow map range. The more the range, the less the resolution (default value is 5 meters)
|-
|<tt>--prop:/sim/rendering/shadows/map-size=<power-of-two></tt>
|Set the shadow map size. Useful values are 1024, 2048, 4096 or 8192. Few cards have the resources to support 16384.
|-
|<tt>--prop:/sim/rendering/shadows/num-cascades</tt>
|Set the shadow map cascade number. Less cascades means less time spent in shadow map generation, but also means lower shadow quality. Integer between 1 and 4.
|-
|<tt>--prop:/sim/rendering/shadows/cascade-far-m[i]</tt>
(1 <= i <= <tt>/sim/rendering/shadows/num-cascades</tt> <= 4)
|Set the shadow map cascade range for each cascade. Default values are 5m, 50m, 500m and 5000m for 4 cascades.
|-
|<tt>--prop:/sim/rendering/rembrandt/no-16bit-buffer=false</tt>
|By default, Rembrandt uses 8 bit buffers for normals (so the property is set to true by default). This may create banding artifacts on specular highlights. If it's unacceptable and the GPU supports it, set to false to have better precision for normals and effects relying on normal direction.
|}

== Guidelines for shader writers ==
=== Predefined uniforms ===
These glsl uniforms don't need to be declared in the effect file.
{| class="wikitable"
!Name
!Type
!Purpose
|-
|<tt>fg_ViewMatrix</tt>
|<tt>mat4</tt>
|In fullscreen pass only, view matrix used to transform the screen position to view direction
|-
|<tt>fg_ViewMatrixInverse</tt>
|<tt>mat4</tt>
|In fullscreen pass only, view matrix inverse used to transform the screen position to view direction
|-
|<tt>fg_ProjectionMatrixInverse</tt>
|<tt>mat4</tt>
|In fullscreen pass only, projection matrix inverse used to transform the screen position to view direction
|-
|<tt>fg_SunAmbientColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunDiffuseColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunSpecularColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunDirection</tt>
|<tt>vec3</tt>
|
|-
|<tt>fg_FogColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_FogDensity</tt>
|<tt>float</tt>
|
|-
|<tt>fg_ShadowNumber</tt>
|<tt>int</tt>
|
|-
|<tt>fg_ShadowDistances</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_DepthInColor</tt>
|<tt>bool</tt>
|Tells if the depth is stored in a depth texture or a color texture
|-
|<tt>fg_Planes</tt>
|<tt>vec3</tt>
|Used to convert the value of the depth buffer to a depth that can be used to compute the eye space position of the fragment
|-
|<tt>fg_BufferSize</tt>
|<tt>vec2</tt>
|Dimensions of the buffer, used to convert gl_FragCoord into the range [0..1][0..1]
|-
|<tt>osg_ViewMatrix</tt>
|<tt>mat4</tt>
|Defined by OSG, used only when working on actual geometry
|-
|<tt>osg_ViewMatrixInverse</tt>
|<tt>mat4</tt>
|Defined by OSG, used only when working on actual geometry
|}
They still have to be declared in the fragment or the vertex shader to be used.

=== Utility functions ===

To ease the maintenance of shaders, several utility functions are available for the fragment shader. These functions are put together in two files : <tt>gbuffer-functions.frag</tt> and <tt>gbuffer-encode.frag</tt>.

==== gbuffer-encode.frag ====

;<tt>void encode_gbuffer(vec3 normal, vec3 color, int mId, float specular, float shininess, float emission, float depth)</tt>
:Used to encode all the values of the G-Buffer in material shaders

==== gbuffer-functions.frag ====

;<tt>vec2 normal_encode(vec3 n)</tt>
:Used to compress normals into the G-Buffer in material shaders. Normally called from <tt>encode_gbuffer()</tt>

;<tt>vec3 normal_decode(vec2 enc)</tt>
:Reconstruct normals from the G-Buffer. Used in fullscreen shaders and light shaders

;<tt>vec3 float_to_color(in float f)</tt>
:Encode float values in the range [0..1] in the 24 bits of a color. This function is used by <tt>encode_gbuffer()</tt> if the <tt>/sim/rendering/use-color-for_depth</tt> is true, for old cards that don't provide depth information with enough resolution inside fullscreen or light shaders.

;<tt>float color_to_float(vec3 color)</tt>
:Decode float values in the range [0..1] from the 24 bits of a color. This function is used by <tt>position()</tt> if the <tt>/sim/rendering/use-color-for_depth</tt> is true, for old cards that don't provide depth information with enough resolution inside fullscreen or light shaders.

;<tt>vec3 position( vec3 viewDir, float depth )</tt>
:Reconstruct eye space position from the view direction and the depth read from the depth buffer

;<tt>vec3 position( vec3 viewDir, vec3 depthColor )</tt>
:Reconstruct eye space position from the view direction and the depth encoded in a color read from the depth buffer

;<tt>vec3 position( vec3 viewDir, vec2 coords, sampler2D depth_tex )</tt>
:Reconstruct eye space position from the view direction and the depth buffer (real depth or color, according to the value of <tt>/sim/rendering/use-color-for_depth</tt>) at a given fragment on screen, given by <tt>coords</tt>

==== Usage ====

For material shaders, it is necessary to provide both <tt>gbuffer-functions.frag</tt> and <tt>gbuffer-encode.frag</tt> in the effect file, like this :

<syntaxhighlight lang="xml">
<program>
<vertex-shader>Shaders/ubershader.vert</vertex-shader>
<fragment-shader>Shaders/ubershader-gbuffer.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-functions.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-encode.frag</fragment-shader>
</program>
</syntaxhighlight>

For fullscreen passes shaders, only <tt>gbuffer-functions.frag</tt> should be provided, like this :

<syntaxhighlight lang="xml">
<program>
<vertex-shader>Shaders/sunlight.vert</vertex-shader>
<fragment-shader>Shaders/sunlight.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-functions.frag</fragment-shader>
</program>
</syntaxhighlight>

In the main function of the shader, the functions referenced need to be declared first. With no #include files, the whole function prototype needs to be typed :
<syntaxhighlight lang="glsl">
void encode_gbuffer(vec3 normal, vec3 color, int mId, float specular, float shininess, float emission, float depth);

main() {
vec3 normal;
vec3 color;
int mId;
float specular;
float shininess;
float emission;
float depth;

// Do shader computations

encode_gbuffer(normal, color, mId, specular, shininess, emission, depth);
}
</syntaxhighlight>

=== Geometry Stage ===
The Geometry Stage is there to fill the G-buffer. '''Shading doesn't occur at this stage, so light or fog computation should not be part of the shader'''. The required operation in the Fragment Shader is to fill every individual buffer with sensible value :

{| class="wikitable" style="text-align: center;"
|depth (gl_FragDepth)||GL_DEPTH_COMPONENT32||colspan="4"|Fragment depth
|-
|gl_FragData[0]||GL_RG16||colspan="2"|normal.x * 0.5 + 0.5||colspan="2"|normal.y * 0.5 + 0.5
|-
|gl_FragData[1]||GL_RGBA8||diffuse.r||diffuse.g||diffuse.b||material id * 1/255.0
|-
|gl_FragData[2]||GL_RGBA8||specular.l||specular.s||emission.l||pixel valid if != 0
|}

This is the default layout expected by the sunlight shader. material Id can be used to detect a different layout



=== Additional light pass ===
There would be a single shader for each light type used. The plan is to create lights like animations in the model XML file. The light shader will retrieve scene geometry by combining screen space position converted in view space ray by the inverse of the projection matrix (an helper function should be provided), and the fragment depth at that screen position read from the depth buffer. With the help of the fragment normal, the diffuse and specular color and the properties of the light the shader implements, it will be possible to add to the lighting buffer the contribution of the light rendered.

=== Fog Pass ===
Using the fragment depth, it will be possible to compute any fog distribution. For the moment, the simple fog equation is implemented.

=== Bloom Pass ===
This is a two-pass effect that blurs the lighting buffer in a small texture. This texture is then added to the lighting buffer at the display stage.

=== Required Effects ===
Several pass are implemented using the effect system. For this purpose, some effects are referenced in the core code using reserved names. these effects are:
{| class="wikitable" cellpadding="3"
!Name
!Kind
!Purpose
|-
|<tt>Effects/ssao</tt>
|Works on a full screen quad
|Compute ambient occlusion from the normal buffer and the depth buffer
|-
|<tt>Effects/ambient</tt>
|Works on a full screen quad
|Copies the diffuse color buffer multiplied by the ambient light to the lighting buffer. Ambient Occlusion can also affect ambient light.
|-
|<tt>Effects/light-spot</tt>
|Works on real geometry of the light volume
|Computes the light contribution of a spot light defined in a <tt>light</tt> animation having a <tt>light-type</tt> of '''<tt>spot</tt>'''
|-
|<tt>Effects/fog</tt>
|Works on a full screen quad
|Computes the fog from the G-buffer and the lighting parameters
|-
|<tt>Effects/display</tt>
|Works on a full screen quad
|Renders the composite final image from the G-buffer and the lighting buffer
|}

== Guidelines for modelers ==

=== Porting aircraft ===
* Rembrandt computes shadows => no more fake shadows in the model
* Rembrandt computes ambient occlusion => no ambient occlusion baked into textures
* Rembrandt has light => static lightmap are not needed, emissive color to see models at night is not needed and would interfere
* Rembrandt has glow => incorrectly used emissive colors may blur displays and make some text unreadable. Light size may have to be adjusted
* Rembrandt has strict needs with shaders => shaders need to be adjusted to comply with the new framework otherwise the view will be plain wrong
* Rembrandt can't do transparent surfaces => transparent surface need to be properly registered to render them with the classical path

=== Registering all translucent surfaces ===

Every model is, by default, rendered using the <tt>Effects/model-default</tt> effect. This effect initialize the G-buffer, ignoring transparent surfaces, by doing alpha testing and rendering all the geometry in the default bin. It is not possible to redirect rendering to transparent bins when the associated texture has alpha channel because most models use a single texture atlas and even opaque parts are rendered with texture with alpha channel.

If a model needs to have transparent or translucent surfaces, these surface objects need to be assigned a different effect that sets explicitly the render bin to "DepthSortedBin", or sets the rendering hint to "transparent". This tells the renderer to render this object using forward rendering, so lighting and fog need to be enabled, and if a shader program is used, they should be computed in the classical way. The <tt>Effects/model-transparent</tt> can be used to register simple transparent/translucent surfaces. You assign this effect to an object (or multiple objects) like:
<effect>
<inherits-from>Effects/model-transparent</inherits-from>
<object-name>TheObject</object-name>
</effect>

If opaque surface need to have special effect, for example to apply bump mapping, this effect should use the "RenderBin" bin, or the rendering hint set to "opaque", and the G-buffer needs to be initialized correctly in the Geometry stage.

=== Adding lights to a model ===

There are two things to consider: the appearance of the light source and the illuminated area. For the appearance of the light source (what you see when you look at the bulb), you need a model with an emissive material that will produce the glow effect and that is visible at night.

For the effect of the source on its environment (the lit area), we must have in the 3D model (the .ac file) a volume that includes the effect (Light Volume). It can be a large cone for spotlights or a sphere for point light. It's important that the light volume is closed, convex and it's normals are oriented outward.

The light volume must be part of the geometry of the model and be referenced in the animation file. No need to add a color or an effect to this volume. Light calculation is only done on the fragments covered by the light volume, but has no influence on the color or the attenuation of the light.

All available animations are possible on the light volume, except '''material''' and '''texture'''. It is not possible to change color of lights for the moment, except switching to another animation. Axis and position are in object space and are transformed by the subsequent animations.

==== Spotlights ====
{|cellpadding=10|
|valign=top|
<syntaxhighlight lang="xml">
<animation>
<type>light</type>
<light-type>spot</light-type>
<name>LightSrcRight</name>
<object-name>LightRight</object-name>
<nopreview/>
<position>
<x>0.169</x>
<y>0.570</y>
<z>0.713</z>
</position>
<direction>
<x>-0.9988</x>
<y>0.0349</y>
<z>-0.0349</z>
</direction>
<ambient>
<r>0.03</r>
<g>0.03</g>
<b>0.03</b>
<a>1.0</a>
</ambient>
<diffuse>
<r>0.7</r>
<g>0.7</g>
<b>0.6</b>
<a>1.0</a>
</diffuse>
<specular>
<r>0.7</r>
<g>0.7</g>
<b>0.7</b>
<a>1.0</a>
</specular>
<dim-factor>
<property>dimming/property</property>

<expression />
<interpolation />
<factor>1</factor>
<offset>0</offset>
<min>0</min>
<max>1</max>

</dim-factor>
<attenuation>
<c>1.0</c>
<l>0.002</l>
<q>0.00005</q>
</attenuation>
<exponent>30.0</exponent>
<cutoff>39</cutoff>
<near-m>3.5</near-m>
<far-m>39</far-m>
</animation>
</syntaxhighlight>
|valign=top|
{| class="wikitable" cellpadding="3"
!Name
!Purpose
|-
|<tt>type</tt>
|Install the <tt>'''light'''</tt> animation
|-
|<tt>light-type</tt>
|This is a <tt>'''spot'''</tt> light
|-
|<tt>name</tt>
|Name given to this animation
|-
|<tt>object-name</tt>
|Name of the light volume in the 3d model (typically a cone with an apex at <tt>position</tt>, along <tt>direction</tt> axis if <tt>cutoff</tt> is lesser than 90 degrees, or a sphere centered at <tt>position</tt> if <tt>cutoff</tt> is greater than 90 degrees )
|-
|<tt>nopreview</tt>
|Hide light volume in fgrun 3d preview
|-
|<tt>position</tt>
|In object space, position of the light
|-
|<tt>direction</tt>
|In object space, direction to the center of the spot
|-
|<tt>ambient</tt>
|Ambient color of the light
|-
|<tt>diffuse</tt>
|Diffuse color of the light
|-
|<tt>specular</tt>
|Specular color of the light
|-
|<tt>dim-factor</tt>
|Group of parameters to control a factor that is applied to ambient, diffuse and specular at the same time
|-
|<tt>attenuation</tt>
|Three element vector. <c> element is the constant factor, <l> element is the linear factor and <q> element is the quadratic factor.<br />
Attenuation of color at distance d is [[File:Spotlight_attenuation.png]]
|-
|<tt>exponent</tt>
|Attenuation is multiplied by <tt>pow( dot( lightDir, <direction> ), <exponent> )</tt>, lightDir being vector from light position to point, in camera space.
|-
|<tt>cutoff</tt>
|Point is lit by this source if <tt>dot( lightDir, <direction> ) > <cutoff></tt> , lightDir being vector from light position to point, in camera space.
|-
|<tt>near-m</tt>
|Minimum distance of influence, from position, in meters
|-
|<tt>far-m</tt>
|Maximum distance of influence, from position, in meters
|}
|}

==== Point lights ====
{|cellpadding=10|
|valign=top|
<syntaxhighlight lang="xml">
<animation>
<type>light</type>
<light-type>point</light-type>
<name>LightSrcRight</name>
<object-name>LightRight</object-name>
<nopreview/>
<position>
<x>0.169</x>
<y>0.570</y>
<z>0.713</z>
</position>
<ambient>
<r>0.03</r>
<g>0.03</g>
<b>0.03</b>
<a>1.0</a>
</ambient>
<diffuse>
<r>0.7</r>
<g>0.7</g>
<b>0.6</b>
<a>1.0</a>
</diffuse>
<specular>
<r>0.7</r>
<g>0.7</g>
<b>0.7</b>
<a>1.0</a>
</specular>
<dim-factor>
<property>dimming/property</property>

<expression />
<interpolation />
<factor>1</factor>
<offset>0</offset>
<min>0</min>
<max>1</max>

</dim-factor>
<attenuation>
<c>1.0</c>
<l>0.002</l>
<q>0.00005</q>
</attenuation>
<near-m>3.5</near-m>
<far-m>39</far-m>
</animation>
</syntaxhighlight>
|valign=top|
{| class="wikitable" cellpadding="3"
!Name
!Purpose
|-
|<tt>type</tt>
|Install the <tt>'''light'''</tt> animation
|-
|<tt>light-type</tt>
|This is a <tt>'''point'''</tt> light
|-
|<tt>name</tt>
|Name given to this animation
|-
|<tt>object-name</tt>
|Name of the light volume in the 3d model (typically a sphere centered on <tt>position</tt>, with a radius of <tt>far-m</tt>)
|-
|<tt>nopreview</tt>
|Hide light volume in fgrun 3d preview
|-
|<tt>position</tt>
|In object space, position of the light
|-
|<tt>ambient</tt>
|Ambient color of the light
|-
|<tt>diffuse</tt>
|Diffuse color of the light
|-
|<tt>specular</tt>
|Specular color of the light
|-
|<tt>dim-factor</tt>
|Group of parameters to control a factor that is applied to ambient, diffuse and specular at the same time
|-
|<tt>attenuation</tt>
|Three element vector. <c> element is the constant factor, <l> element is the linear factor and <q> element is the quadratic factor.<br />
Attenuation of color at distance d is [[File:Spotlight_attenuation.png]]
|-
|<tt>near-m</tt>
|Minimum distance of influence, from position, in meters
|-
|<tt>far-m</tt>
|Maximum distance of influence, from position, in meters
|}
|}

== Initial TODO List ==
*Fix shadow rendering when using multi threading in OSG
*<del>Implement Cascaded Shadow Map (need to be optimized - frustum calculation and night</del>)
*Honor <noshadow> animation directive
*See what happens with glow in fog
*Test multi-screen
*Restore splashscreen
*<del>Draw transparent objects with forward rendering (may need to capture the transparent bin from the geometry stage and move it in the display stage)</del> (OK - needs model contribution)
*<del>Add spotlights as animations (nearly finished)</del>
*<del>find a solution for ambient and emissive color of material (may need an additional buffer)</del>
*implement strength of glow (in the emissive buffer alpha channel)
**provide levels 0 to 5 - we are currently at level 5
**level 0 should be ok for MFDs that are currenly unreadable because blurred
*Provide a shader for transparent objects that could render to the emissive buffer too (using MRT)
*<del>Use stencil buffer to limit light range</del>(no - done in light shader)
**needed for cockpit light to implement fake shadows and avoid lighting the runway from the cabin through the airframe
*Use effect system instead of hard-coded shaders (mostly done)
*Convert existing shaders to deferred rendering
**Modify shadows to allow multiple casters (limited list)
**Implement a priority list of light sources, based on priority and distance from the viewer
**<del>Add new animation to link a light source to a model</del> (need to provide point light animation duplicating spot light)
*Tidy up the architecture
*Restore depth partitioning using depth ranges
*Restore stereo and other options currently available in CameraGroup
*Implement quality vs performance user control

== "Merge in next" TODO List ==
*<del>Design and implement a configurable pipeline</del> (done)
*Implement lightfield shader

== Gallery ==
{{#ev:youtube|PXHhtQb5yzc}} {{#ev:youtube|peEzEapavkg}} {{#ev:youtube|RIetPh8iJXk}} {{#ev:youtube|oaNFrxgQY1c}} {{#ev:youtube|8xGzy12hlis}} {{#ev:youtube|ZyuHBlm3xXU}} {{#ev:youtube|RgH9GZRukOI}} {{#ev:youtube|UQvbHnBkpaM}} {{#ev:youtube|v02phoOqWHE}}{{#ev:youtube|dlSo4sBa7Nk}}

{{Appendix|all|
* {{cite web |url=http://http.download.nvidia.com/developer/presentations/2004/6800_Leagues/6800_Leagues_Deferred_Shading.pdf |title=Deferred Shading |author=Shawn Hargreaves and Mark Harris }}
* {{cite web |url=http://bat710.univ-lyon1.fr/~jciehl/Public/educ/GAMA/2007/Deferred_Shading_Tutorial_SBGAMES2005.pdf |title=Deferred Shading Tutorial |author=Fabio Policarpo and Francisco Fonseca }}
* {{cite web |url=http://www.guerrilla-games.com/publications/dr_kz2_rsx_dev07.pdf |title=Deferred Rendering in Killzone 2 |author=Michal Valient |month=July |year=2007 }}
* {{cite web |url=http://www.anandtech.com/show/5011/nvidiaea-posts-battlefield-3-graphics-tech-talk |title=Battlefield 3 Graphics Tech Talk |author=Johan Andersson |month=October |year=2011 }}
* {{cite web |url=http://www.disney.co.uk/cms_res/blackrockstudio/pdf/Rendering_Techniques_in_SplitSecond.pdf |title=Rendering Techniques in Split/Second |author=Jeremy Moore and David Jefferies |year=2009 }}
* {{cite web |url=http://www.crytek.com/sites/default/files/A_bit_more_deferred_-_CryEngine3.ppt |title="A bit more Deferred" - CryEngine 3 (PPT) |author=Martin Mittring }}
* {{cite web |url=http://http.developer.nvidia.com/GPUGems2/gpugems2_chapter09.html |title=Deferred Shading in S.T.A.L.K.E.R. |author=Oles Shishkovtsov }}
* {{cite web |url=http://http.developer.nvidia.com/GPUGems3/gpugems3_ch19.html |title=Deferred Shading in Tabula Rasa |author=Rusty Koonce }}
* {{cite web |url=http://aras-p.info/texts/CompactNormalStorage.html |title=Compact Normal Storage for small g-buffers |author=Aras Pranckevičius |date=4 August 2009 |accessdate=12 April 2012 }}
* {{cite web |url=http://the-witness.net/news/2010/03/graphics-tech-shadow-maps-part-1/ |title=Graphics Tech: Shadow Maps (part 1) |author=Jonathan Blow |date=3 March 2010 |accessdate=13 April 2012 }}
}}

[[Category:Shader development]]
[[Category:Core development projects]]

User:Mcginnly

2012-05-16T17:15:05Z

Mcginnly: /* Links */

==Links==
*[[Howto:Animate models]]
*[[Howto:Make a clickable panel]]
*[[Creating instruments for FG]]
*[[Bindings]]

User:Mcginnly

2012-05-16T17:14:10Z

Mcginnly: /* Links */

==Links==
*[[Howto:Animate models]]
*[[Howto:Make a clickable panel]]
*[[Creating instruments for FG]]

User:Mcginnly

2012-05-16T17:13:09Z

Mcginnly:

==Links==
*[[Howto:Animate models]]
*[[Howto:Make a clickable panel]]

User:Mcginnly

2012-05-16T15:16:33Z

Mcginnly: Created page with "==Links== *Howto:Animate models"

==Links==
*[[Howto:Animate models]]

Talk:Map dialog

2012-05-16T13:56:52Z

Mcginnly: taxiways?

==Unplanned improvements==
How about taxiway designations? --[[User:Mcginnly|Mcginnly]] 09:56, 16 May 2012 (EDT)

Project Rembrandt

2012-05-15T00:36:26Z

Mcginnly: /* Repositories */

{{WIP}}
== Why this name ? ==
[http://en.wikipedia.org/wiki/Rembrandt Rembrandt] was a dutch painter living in the 17th century, famous as one of the master of [http://en.wikipedia.org/wiki/Chiaroscuro chiaroscuro].

This project is about changing the way [[FlightGear]] renders lights, [[shadows]] and shades, and aims at making Rembrandt painting style possible in FG.

== What is it ? ==
The idea driving the project is to implement [http://en.wikipedia.org/wiki/Deferred_shading deferred rendering] inside FlightGear.
From the beginning FlightGear had a forward renderer that tries to render all properties of an object in one pass (shading, lighting, fog, ...), making it difficult to render more sophisticated shading
(see the [[FlightGear Newsletter December 2011#Shaders|'Uber-shader']]) because one has to take into account all aspects of the [http://www.wired.com/magazine/2010/07/st_equation_3danimation/ rendering equation].

[[Image:project_rembrandt_1.png|thumb|300px|Main view with the content of buffers displayed at corners]]
On the contrary, deferred rendering is about separating operations in simplified stages and collecting the intermediary results in hidden buffers that can be used by the next stage.

;First stage is the Geometry Stage :
: we render all the scene into 4 textures, using multi render targets, to do it in one pass: one for the depth buffer, one for the normals (lower left of the image), one for the diffuse colors (lower right) and one for the specular colors (upper right).

;Next stage is the Shadow Stage :
: we render the scene again into a depth texture from the point of view of the lights. There will be one texture for every light casting shadows.

;Then comes the Lighting Stage, with several substages :
:*<u>Sky pass</u>: the sky is first drawn using classical method.
:*<u>Ambient pass</u>: the diffuse buffer is modulated with the ambient color of the scene and is drawn as a screen-aligned textured quad
:*<u>Sunlight pass</u>: a second screen aligned quad is drawn and a shader computes the view position of every pixel to compute its diffuse and specular color, using the normal stored in the first stage. The resulting color is blended with the previous pass. Shadows are computed here by comparing the position of the pixel with the position of the light occluder stored in the shadow map.
:*<u>Additional light pass</u>: the scene graph will be traversed another time to display light volumes (cone or frusta for spot lights, sphere for omni-directional lights) and their shader will add the light contributed by the source only on pixels receiving light.
:*<u>Fog pass</u>: a new screen aligned quad is draw and the position of the pixel is computed to evaluate the amount of fog the pixel has. The fog color is blended with the result of the previous stage.
:*<u>Transparent objects pass</u>: transparent objects (and clouds) are finally rendered using classical method.

:All lighting computations are accumulated in a single buffer that will be used for the last stage, in addition of the one computed by the Geometry stage.

;In the end, the Display Stage, with optional Post-Processing effect :
:The results of the previous buffers are pushed to the main framebuffer to be displayed, optionally modified to show Glow, Motion blur, HDR, redout or blackout, screen-space ambient occlusion, anti-aliasing, etc...

In FG, we end the rendering pipeline by displaying the [[Menubar|GUI]] and the [[HUD]].

All these stages are more precisely described if this [http://bat710.univ-lyon1.fr/~jciehl/Public/educ/GAMA/2007/Deferred_Shading_Tutorial_SBGAMES2005.pdf tutorial] that is the basis of the current code, with some addition and modifications.

== Caveats ==
Deferred rendering is not capable to display transparent. For the moment, clouds are renderer separately and should be lit and shaded by their own. Transparent surfaces are alpha-tested and not blended. They would have to be drawn in their own bin over the composited image.

It also don't fit with depth partitioning because the depth buffer should be kept to retain the view space position, so for the moment, z-fighting is quite visible. Depth partitioning with non overlapping depth range might be the solution and should be experimented at one point.

The glow pass can make certain MFD (that use emissive color) unreadable because blurred. Should be treated as transparent.

== Implementation ==
=== Repositories ===
The code is in the main branch of the [[FlightGear and Git|official repository]]. Any other location is not maintained anymore.

=== Rendering of transparent surfaces ===
[[Image:project_rembrandt_5.png|thumb|300px|Transparent surfaces drawn after opaque objects]]
Transparent surfaces are detected by OSG loader plugins and their state set receive the TRANSPARENT_BIN rendering hint. In the culling pass, the cull visitor orders transparent surfaces in transparent bin. In a cull callback attached to the Geometry camera, after the scenegraph traversal, the transparent bins are removed from the render stage and saved in a temporary collection. In a cull callback attached to the Lighting camera, after the scenegraph traversal, the transparent bins saved at the previous stage, are added to the render stage of the Lighting camera with a high order num. That way, the transparent surface are drawn on top of the scene lighted from the Gbuffer.

=== Memory consumption ===
For each camera defined in the camera group, there is a separate shadow map, so the video memory usage is :
* G-buffer and Lighting buffer: 20 bytes per pixel. For an HD screen (1920x1080) memory requirement is 40 Mb
* Shadow map: 3 x shadow_map_size x shadow_map_size bytes (if size is 8192, whole map size is 192 Mb
Not counting textures, display list or vertex buffers for models and terrain

3 HD screens require 120 Mb of memory for the buffers (shadow excluded), you're asking 3x8192x8192x3 = 576 Mb (megabytes) of memory for the shadows alone.

If you are seeing error messages during startup or FlightGear doesn't start up properly, it's probably because you don't have enough free video memory. Reduce the size of the shadow map in preferences.xml by locating

<syntaxhighlight lang="xml">
<map-size type="int">8192</map-size>
</syntaxhighlight>

And put 4096 or 2048 instead.
You can also use a startup parameter: --prop:/sim/rendering/shadows/map-size=2048

=== Configurable pipeline ===

The Rembrandt renderer uses an XML file to setup its pipeline for each viewport described in the camera group. This file describes the way the intermediary buffers are setup and how the different rendering stages are sequenced. The general outline of a pipeline file is as follow :

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<PropertyList>

<buffer>

</buffer>
<buffer>

</buffer>


<stage>

</stage>
<stage>

</stage>
</PropertyList>
</syntaxhighlight>

==== Buffers ====
A buffer is a texture used as a storage area in the GPU. It's size is usually a multiple of the screen size, but fixed size is supported (typical for shadow map). The description of a buffer is described below :

<syntaxhighlight lang="xml">
<buffer>
<name>buffer-name</name>
<internal-format>rgba8</internal-format> 
<source-format>rgba</source-format> 
<source-type>unsigned-byte</source-type> 
<width>screen</width> 
<height>screen</height> 
<scale-factor>1.0</scale-factor>
<wrap-mode>clamp-to-border</wrap-mode> 

<shadow-comparison>true</shadow-comparison>

<condition>

</condition>
</buffer>
</syntaxhighlight>

==== Stages ====
A stage is an unit of rendering to a group of buffer. Most stages are predefined and their type is not free. When a type is not specified, the name is used. Stage types are :
{| class="wikitable"
!align="left"| Stage type
!align="left"| Purpose
|-
|geometry
|The geometry stage initialize most of the buffers and works on the real objects and geometry. Transparent objects are set aside and will be used untouched in the lighting stage. Other opaque geometry is rendered with the standard effects that do the hard work to put sensible data in the buffers.
|-
|shadow
|In this stage, the geometry is rendered in the normal map from the perspective of the sun.
|-
|lighting
|This stage uses the buffers filled by the previous stages to light every pixel of the scene. The result is rendered in another buffer to allow post effects.
|-
|fullscreen
|Stages of this type are used to alter the whole scene or transform data from a particular buffer.
|-
|display
|Final rendering of the scene to the screen or the texture defined in the camera group.
|}

A stage description is outlined below :
<syntaxhighlight lang="xml">
<stage>
<name>stage-name</name>
<type>stage-type</type> 
<order-num>-1</order-num>
<effect>Effects/fullscreen-effect</effect> 
<needs-du-dv>true</needs-du-dv> 
<scale-factor>0.25</scale-factor> 


<condition>

</condition>

<attachment>

</attachment>
<attachment>

</attachment>


<pass>

</pass>
<pass>

</pass>
</stage>
</syntaxhighlight>
Stages render in buffers (except for the display stage). Attachments describe which buffers are affected by each stage.

===== Attachments =====
Attachment describe bindings between buffer and attachment point :
<syntaxhighlight lang="xml">
<attachment>
<component>color0</component> 
<buffer>buffer-name</buffer>

<condition>

</condition>
</attachment>
</syntaxhighlight>

===== Passes =====
Passes are only available in the <tt>lighting</tt> stage. Three kind of stage are allowed :

{| class="wikitable"
!align="left"| Pass type
!align="left"| Purpose
|-
|sky-clouds
|Renders the skydome, sun, moon, planet, stars and clouds
|-
|lights
|Renders additional spot and point lights
|-
|fullscreen
|Fullscreen pass analog to a fullscreen stage except that it renders in the buffers attached to the lighting stage
|}
<syntaxhighlight lang="xml">
<pass>
<name>pass-name</name>
<type>pass-type</type> 
<order-num>-1</order-num>
<effect>Effects/fullscreen-effect</effect> 


<condition>

</condition>
</pass>
</syntaxhighlight>

== Running Flightgear with Rembrandt ==

The Rembrandt renderer is now integrated in the main repository but needs to be enabled to run. Use the <tt>--enable-rembrandt</tt> option to start Flightgear with this new renderer.

Rembrandt is quite demanding in GPU resources and may fail to run with the default options. The more frequent symptom is an OSG message in the console :

RenderStage::runCameraSetUp(), FBO setup failed, FBO status= 0x8cd6
Warning: RenderStage::runCameraSetUp(State&) Pbuffer does not support multiple color outputs.

Some card also exhibit messages like this :

glLinkProgram "" FAILED
Program "" infolog:
Fragment info
-------------
0(37) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(36) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(35) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable
0(34) : error C6013: Only arrays of texcoords may be indexed in this profile, and only with a loop index variable

There is a number of additional options that can help to avoid these problems :

{| class="wikitable"
|<tt>--prop:/sim/rendering/rembrandt/use-color-for-depth=true</tt>
|Some old NVidia cards, such as 7600GT, don't give enough resolution for depth and that result in "fog curtains" at few meters from the viewer. One trick is to encode depth in another texture and get the proper value afterward. This option enables that.
|-
|<tt>--prop:/sim/rendering/shadows/enabled=false</tt>
|Disable shadows altogether. This setting is changeable at runtime in the rendering option dialog.
|-
|<tt>--prop:/sim/rendering/shadows/num-cascades=1</tt>
|Avoid the "error C6013" message on old cards at the cost of resolution in the cockpit. Set <tt>/sim/rendering/shadows/cascade-far-m[0]</tt> to change the shadow map range. The more the range, the less the resolution (default value is 5 meters)
|-
|<tt>--prop:/sim/rendering/shadows/map-size=<power-of-two></tt>
|Set the shadow map size. Useful values are 1024, 2048, 4096 or 8192. Few cards have the resources to support 16384.
|-
|<tt>--prop:/sim/rendering/shadows/num-cascades</tt>
|Set the shadow map cascade number. Less cascades means less time spent in shadow map generation, but also means lower shadow quality. Integer between 1 and 4.
|-
|<tt>--prop:/sim/rendering/shadows/cascade-far-m[i]</tt>
(1 <= i <= <tt>/sim/rendering/shadows/num-cascades</tt> <= 4)
|Set the shadow map cascade range for each cascade. Default values are 5m, 50m, 500m and 5000m for 4 cascades.
|-
|<tt>--prop:/sim/rendering/rembrandt/no-16bit-buffer=false</tt>
|By default, Rembrandt uses 8 bit buffers for normals (so the property is set to true by default). This may create banding artifacts on specular highlights. If it's unacceptable and the GPU supports it, set to false to have better precision for normals and effects relying on normal direction.
|}

== Guidelines for shader writers ==
=== Predefined uniforms ===
These glsl uniforms don't need to be declared in the effect file.
{| class="wikitable"
!Name
!Type
!Purpose
|-
|<tt>fg_ViewMatrix</tt>
|<tt>mat4</tt>
|In fullscreen pass only, view matrix used to transform the screen position to view direction
|-
|<tt>fg_ViewMatrixInverse</tt>
|<tt>mat4</tt>
|In fullscreen pass only, view matrix inverse used to transform the screen position to view direction
|-
|<tt>fg_ProjectionMatrixInverse</tt>
|<tt>mat4</tt>
|In fullscreen pass only, projection matrix inverse used to transform the screen position to view direction
|-
|<tt>fg_SunAmbientColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunDiffuseColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunSpecularColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_SunDirection</tt>
|<tt>vec3</tt>
|
|-
|<tt>fg_FogColor</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_FogDensity</tt>
|<tt>float</tt>
|
|-
|<tt>fg_ShadowNumber</tt>
|<tt>int</tt>
|
|-
|<tt>fg_ShadowDistances</tt>
|<tt>vec4</tt>
|
|-
|<tt>fg_DepthInColor</tt>
|<tt>bool</tt>
|Tells if the depth is stored in a depth texture or a color texture
|-
|<tt>fg_Planes</tt>
|<tt>vec3</tt>
|Used to convert the value of the depth buffer to a depth that can be used to compute the eye space position of the fragment
|-
|<tt>fg_BufferSize</tt>
|<tt>vec2</tt>
|Dimensions of the buffer, used to convert gl_FragCoord into the range [0..1][0..1]
|-
|<tt>osg_ViewMatrix</tt>
|<tt>mat4</tt>
|Defined by OSG, used only when working on actual geometry
|-
|<tt>osg_ViewMatrixInverse</tt>
|<tt>mat4</tt>
|Defined by OSG, used only when working on actual geometry
|}
They still have to be declared in the fragment or the vertex shader to be used.

=== Utility functions ===

To ease the maintenance of shaders, several utility functions are available for the fragment shader. These functions are put together in two files : <tt>gbuffer-functions.frag</tt> and <tt>gbuffer-encode.frag</tt>.

==== gbuffer-encode.frag ====

;<tt>void encode_gbuffer(vec3 normal, vec3 color, int mId, float specular, float shininess, float emission, float depth)</tt>
:Used to encode all the values of the G-Buffer in material shaders

==== gbuffer-functions.frag ====

;<tt>vec2 normal_encode(vec3 n)</tt>
:Used to compress normals into the G-Buffer in material shaders. Normally called from <tt>encode_gbuffer()</tt>

;<tt>vec3 normal_decode(vec2 enc)</tt>
:Reconstruct normals from the G-Buffer. Used in fullscreen shaders and light shaders

;<tt>vec3 float_to_color(in float f)</tt>
:Encode float values in the range [0..1] in the 24 bits of a color. This function is used by <tt>encode_gbuffer()</tt> if the <tt>/sim/rendering/use-color-for_depth</tt> is true, for old cards that don't provide depth information with enough resolution inside fullscreen or light shaders.

;<tt>float color_to_float(vec3 color)</tt>
:Decode float values in the range [0..1] from the 24 bits of a color. This function is used by <tt>position()</tt> if the <tt>/sim/rendering/use-color-for_depth</tt> is true, for old cards that don't provide depth information with enough resolution inside fullscreen or light shaders.

;<tt>vec3 position( vec3 viewDir, float depth )</tt>
:Reconstruct eye space position from the view direction and the depth read from the depth buffer

;<tt>vec3 position( vec3 viewDir, vec3 depthColor )</tt>
:Reconstruct eye space position from the view direction and the depth encoded in a color read from the depth buffer

;<tt>vec3 position( vec3 viewDir, vec2 coords, sampler2D depth_tex )</tt>
:Reconstruct eye space position from the view direction and the depth buffer (real depth or color, according to the value of <tt>/sim/rendering/use-color-for_depth</tt>) at a given fragment on screen, given by <tt>coords</tt>

==== Usage ====

For material shaders, it is necessary to provide both <tt>gbuffer-functions.frag</tt> and <tt>gbuffer-encode.frag</tt> in the effect file, like this :

<syntaxhighlight lang="xml">
<program>
<vertex-shader>Shaders/ubershader.vert</vertex-shader>
<fragment-shader>Shaders/ubershader-gbuffer.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-functions.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-encode.frag</fragment-shader>
</program>
</syntaxhighlight>

For fullscreen passes shaders, only <tt>gbuffer-functions.frag</tt> should be provided, like this :

<syntaxhighlight lang="xml">
<program>
<vertex-shader>Shaders/sunlight.vert</vertex-shader>
<fragment-shader>Shaders/sunlight.frag</fragment-shader>
<fragment-shader>Shaders/gbuffer-functions.frag</fragment-shader>
</program>
</syntaxhighlight>

In the main function of the shader, the functions referenced need to be declared first. With no #include files, the whole function prototype needs to be typed :
<syntaxhighlight lang="glsl">
void encode_gbuffer(vec3 normal, vec3 color, int mId, float specular, float shininess, float emission, float depth);

main() {
vec3 normal;
vec3 color;
int mId;
float specular;
float shininess;
float emission;
float depth;

// Do shader computations

encode_gbuffer(normal, color, mId, specular, shininess, emission, depth);
}
</syntaxhighlight>

=== Geometry Stage ===
The Geometry Stage is there to fill the G-buffer. '''Shading doesn't occur at this stage, so light or fog computation should not be part of the shader'''. The required operation in the Fragment Shader is to fill every individual buffer with sensible value :

{| class="wikitable" style="text-align: center;"
|depth (gl_FragDepth)||GL_DEPTH_COMPONENT32||colspan="4"|Fragment depth
|-
|gl_FragData[0]||GL_RG16||colspan="2"|normal.x * 0.5 + 0.5||colspan="2"|normal.y * 0.5 + 0.5
|-
|gl_FragData[1]||GL_RGBA8||diffuse.r||diffuse.g||diffuse.b||material id * 1/255.0
|-
|gl_FragData[2]||GL_RGBA8||specular.l||specular.s||emission.l||pixel valid if != 0
|}

This is the default layout expected by the sunlight shader. material Id can be used to detect a different layout



=== Additional light pass ===
There would be a single shader for each light type used. The plan is to create lights like animations in the model XML file. The light shader will retrieve scene geometry by combining screen space position converted in view space ray by the inverse of the projection matrix (an helper function should be provided), and the fragment depth at that screen position read from the depth buffer. With the help of the fragment normal, the diffuse and specular color and the properties of the light the shader implements, it will be possible to add to the lighting buffer the contribution of the light rendered.

=== Fog Pass ===
Using the fragment depth, it will be possible to compute any fog distribution. For the moment, the simple fog equation is implemented.

=== Bloom Pass ===
This is a two-pass effect that blurs the lighting buffer in a small texture. This texture is then added to the lighting buffer at the display stage.

=== Required Effects ===
Several pass are implemented using the effect system. For this purpose, some effects are referenced in the core code using reserved names. these effects are:
{| class="wikitable" cellpadding="3"
!Name
!Kind
!Purpose
|-
|<tt>Effects/ssao</tt>
|Works on a full screen quad
|Compute ambient occlusion from the normal buffer and the depth buffer
|-
|<tt>Effects/ambient</tt>
|Works on a full screen quad
|Copies the diffuse color buffer multiplied by the ambient light to the lighting buffer. Ambient Occlusion can also affect ambient light.
|-
|<tt>Effects/light-spot</tt>
|Works on real geometry of the light volume
|Computes the light contribution of a spot light defined in a <tt>light</tt> animation having a <tt>light-type</tt> of '''<tt>spot</tt>'''
|-
|<tt>Effects/fog</tt>
|Works on a full screen quad
|Computes the fog from the G-buffer and the lighting parameters
|-
|<tt>Effects/display</tt>
|Works on a full screen quad
|Renders the composite final image from the G-buffer and the lighting buffer
|}

== Guidelines for modelers ==

=== Porting aircraft ===
* Rembrandt computes shadows => no more fake shadows in the model
* Rembrandt computes ambient occlusion => no ambient occlusion baked into textures
* Rembrandt has light => static lightmap are not needed, emissive color to see models at night is not needed and would interfere
* Rembrandt has glow => incorrectly used emissive colors may blur displays and make some text unreadable. Light size may have to be adjusted
* Rembrandt has strict needs with shaders => shaders need to be adjusted to comply with the new framework otherwise the view will be plain wrong
* Rembrandt can't do transparent surfaces => transparent surface need to be properly registered to render them with the classical path

=== Registering all translucent surfaces ===

Every model is, by default, rendered using the <tt>Effects/model-default</tt> effect. This effect initialize the G-buffer, ignoring transparent surfaces, by doing alpha testing and rendering all the geometry in the default bin. It is not possible to redirect rendering to transparent bins when the associated texture has alpha channel because most models use a single texture atlas and even opaque parts are rendered with texture with alpha channel.

If a model needs to have transparent or translucent surfaces, these surface objects need to be assigned a different effect that sets explicitly the render bin to "DepthSortedBin", or sets the rendering hint to "transparent". This tells the renderer to render this object using forward rendering, so lighting and fog need to be enabled, and if a shader program is used, they should be computed in the classical way. The <tt>Effects/model-transparent</tt> can be used to register simple transparent/translucent surfaces. You assign this effect to an object (or multiple objects) like:
<effect>
<inherits-from>Effects/model-transparent</inherits-from>
<object-name>TheObject</object-name>
</effect>

If opaque surface need to have special effect, for example to apply bump mapping, this effect should use the "RenderBin" bin, or the rendering hint set to "opaque", and the G-buffer needs to be initialized correctly in the Geometry stage.

=== Adding lights to a model ===

There are two things to consider: the appearance of the light source and the illuminated area. For the appearance of the light source (what you see when you look at the bulb), you need a model with an emissive material that will produce the glow effect and that is visible at night.

For the effect of the source on its environment (the lit area), we must have in the 3D model (the .ac file) a volume that includes the effect (Light Volume). It can be a large cone for spotlights or a sphere for point light. It's important that the light volume is closed, convex and it's normals are oriented outward.

The light volume must be part of the geometry of the model and be referenced in the animation file. No need to add a color or an effect to this volume. Light calculation is only done on the fragments covered by the light volume, but has no influence on the color or the attenuation of the light.

All available animations are possible on the light volume, except '''material''' and '''texture'''. It is not possible to change color of lights for the moment, except switching to another animation. Axis and position are in object space and are transformed by the subsequent animations.

==== Spotlights ====
{|cellpadding=10|
|valign=top|
<syntaxhighlight lang="xml">
<animation>
<type>light</type>
<light-type>spot</light-type>
<name>LightSrcRight</name>
<object-name>LightRight</object-name>
<nopreview/>
<position>
<x>0.169</x>
<y>0.570</y>
<z>0.713</z>
</position>
<direction>
<x>-0.9988</x>
<y>0.0349</y>
<z>-0.0349</z>
</direction>
<ambient>
<r>0.03</r>
<g>0.03</g>
<b>0.03</b>
<a>1.0</a>
</ambient>
<diffuse>
<r>0.7</r>
<g>0.7</g>
<b>0.6</b>
<a>1.0</a>
</diffuse>
<specular>
<r>0.7</r>
<g>0.7</g>
<b>0.7</b>
<a>1.0</a>
</specular>
<dim-factor>
<property>dimming/property</property>

<expression />
<interpolation />
<factor>1</factor>
<offset>0</offset>
<min>0</min>
<max>1</max>

</dim-factor>
<attenuation>
<c>1.0</c>
<l>0.002</l>
<q>0.00005</q>
</attenuation>
<exponent>30.0</exponent>
<cutoff>39</cutoff>
<near-m>3.5</near-m>
<far-m>39</far-m>
</animation>
</syntaxhighlight>
|valign=top|
{| class="wikitable" cellpadding="3"
!Name
!Purpose
|-
|<tt>type</tt>
|Install the <tt>'''light'''</tt> animation
|-
|<tt>light-type</tt>
|This is a <tt>'''spot'''</tt> light
|-
|<tt>name</tt>
|Name given to this animation
|-
|<tt>object-name</tt>
|Name of the light volume in the 3d model (typically a cone with an apex at <tt>position</tt>, along <tt>direction</tt> axis if <tt>cutoff</tt> is lesser than 90 degrees, or a sphere centered at <tt>position</tt> if <tt>cutoff</tt> is greater than 90 degrees )
|-
|<tt>nopreview</tt>
|Hide light volume in fgrun 3d preview
|-
|<tt>position</tt>
|In object space, position of the light
|-
|<tt>direction</tt>
|In object space, direction to the center of the spot
|-
|<tt>ambient</tt>
|Ambient color of the light
|-
|<tt>diffuse</tt>
|Diffuse color of the light
|-
|<tt>specular</tt>
|Specular color of the light
|-
|<tt>dim-factor</tt>
|Group of parameters to control a factor that is applied to ambient, diffuse and specular at the same time
|-
|<tt>attenuation</tt>
|Three element vector. <c> element is the constant factor, <l> element is the linear factor and <q> element is the quadratic factor.<br />
Attenuation of color at distance d is [[File:Spotlight_attenuation.png]]
|-
|<tt>exponent</tt>
|Attenuation is multiplied by <tt>pow( dot( lightDir, <direction> ), <exponent> )</tt>, lightDir being vector from light position to point, in camera space.
|-
|<tt>cutoff</tt>
|Point is lit by this source if <tt>dot( lightDir, <direction> ) > <cutoff></tt> , lightDir being vector from light position to point, in camera space.
|-
|<tt>near-m</tt>
|Minimum distance of influence, from position, in meters
|-
|<tt>far-m</tt>
|Maximum distance of influence, from position, in meters
|}
|}

==== Point lights ====
{|cellpadding=10|
|valign=top|
<syntaxhighlight lang="xml">
<animation>
<type>light</type>
<light-type>point</light-type>
<name>LightSrcRight</name>
<object-name>LightRight</object-name>
<nopreview/>
<position>
<x>0.169</x>
<y>0.570</y>
<z>0.713</z>
</position>
<ambient>
<r>0.03</r>
<g>0.03</g>
<b>0.03</b>
<a>1.0</a>
</ambient>
<diffuse>
<r>0.7</r>
<g>0.7</g>
<b>0.6</b>
<a>1.0</a>
</diffuse>
<specular>
<r>0.7</r>
<g>0.7</g>
<b>0.7</b>
<a>1.0</a>
</specular>
<dim-factor>
<property>dimming/property</property>

<expression />
<interpolation />
<factor>1</factor>
<offset>0</offset>
<min>0</min>
<max>1</max>

</dim-factor>
<attenuation>
<c>1.0</c>
<l>0.002</l>
<q>0.00005</q>
</attenuation>
<near-m>3.5</near-m>
<far-m>39</far-m>
</animation>
</syntaxhighlight>
|valign=top|
{| class="wikitable" cellpadding="3"
!Name
!Purpose
|-
|<tt>type</tt>
|Install the <tt>'''light'''</tt> animation
|-
|<tt>light-type</tt>
|This is a <tt>'''point'''</tt> light
|-
|<tt>name</tt>
|Name given to this animation
|-
|<tt>object-name</tt>
|Name of the light volume in the 3d model (typically a sphere centered on <tt>position</tt>, with a radius of <tt>far-m</tt>)
|-
|<tt>nopreview</tt>
|Hide light volume in fgrun 3d preview
|-
|<tt>position</tt>
|In object space, position of the light
|-
|<tt>ambient</tt>
|Ambient color of the light
|-
|<tt>diffuse</tt>
|Diffuse color of the light
|-
|<tt>specular</tt>
|Specular color of the light
|-
|<tt>dim-factor</tt>
|Group of parameters to control a factor that is applied to ambient, diffuse and specular at the same time
|-
|<tt>attenuation</tt>
|Three element vector. <c> element is the constant factor, <l> element is the linear factor and <q> element is the quadratic factor.<br />
Attenuation of color at distance d is [[File:Spotlight_attenuation.png]]
|-
|<tt>near-m</tt>
|Minimum distance of influence, from position, in meters
|-
|<tt>far-m</tt>
|Maximum distance of influence, from position, in meters
|}
|}

== Initial TODO List ==
*Fix shadow rendering when using multi threading in OSG
*<del>Implement Cascaded Shadow Map (need to be optimized - frustum calculation and night</del>)
*Honor <noshadow> animation directive
*See what happens with glow in fog
*Test multi-screen
*Restore splashscreen
*<del>Draw transparent objects with forward rendering (may need to capture the transparent bin from the geometry stage and move it in the display stage)</del> (OK - needs model contribution)
*<del>Add spotlights as animations (nearly finished)</del>
*<del>find a solution for ambient and emissive color of material (may need an additional buffer)</del>
*implement strength of glow (in the emissive buffer alpha channel)
**provide levels 0 to 5 - we are currently at level 5
**level 0 should be ok for MFDs that are currenly unreadable because blurred
*Provide a shader for transparent objects that could render to the emissive buffer too (using MRT)
*<del>Use stencil buffer to limit light range</del>(no - done in light shader)
**needed for cockpit light to implement fake shadows and avoid lighting the runway from the cabin through the airframe
*Use effect system instead of hard-coded shaders (mostly done)
*Convert existing shaders to deferred rendering
**Modify shadows to allow multiple casters (limited list)
**Implement a priority list of light sources, based on priority and distance from the viewer
**<del>Add new animation to link a light source to a model</del> (need to provide point light animation duplicating spot light)
*Tidy up the architecture
*Restore depth partitioning using depth ranges
*Restore stereo and other options currently available in CameraGroup
*Implement quality vs performance user control

== "Merge in next" TODO List ==
*Design and implement a configurable pipeline
*Implement lightfield shader

== Gallery ==
{{#ev:youtube|PXHhtQb5yzc}} {{#ev:youtube|peEzEapavkg}} {{#ev:youtube|RIetPh8iJXk}} {{#ev:youtube|oaNFrxgQY1c}} {{#ev:youtube|8xGzy12hlis}} {{#ev:youtube|ZyuHBlm3xXU}} {{#ev:youtube|RgH9GZRukOI}} {{#ev:youtube|UQvbHnBkpaM}} {{#ev:youtube|v02phoOqWHE}}{{#ev:youtube|dlSo4sBa7Nk}}

== Model modification log ==
;c172p
:Add an effect to the propeller disk (object Propeller.Fast) to put it in a transparent bin
;Models/Airport/apt-light.xml & Models/Airport/apt-light-ba.ac
:Add a spot light animation and a light volume
;Scenery/Objects/w130n30/w123n37/942050.stg
:Change KSFO_light.xml to apt-light.xml
;Aircraft/followme/Models/followme.xml & .ac
:Add light volumes and spotlight animations for headlights

== Effect/Shader modification log ==
;Default shaders
:render to the G-buffer
;Urban effect
:render to the G-buffer
;Spot light effect
:new effect to render spot lights from the animation file
;model-transparent
:new effect to classify transparent surfaces (those that are not bound to the glass shader or other shader that use explicitly the transparent bin )

{{Appendix|all|
* {{cite web |url=http://http.download.nvidia.com/developer/presentations/2004/6800_Leagues/6800_Leagues_Deferred_Shading.pdf |title=Deferred Shading |author=Shawn Hargreaves and Mark Harris }}
* {{cite web |url=http://bat710.univ-lyon1.fr/~jciehl/Public/educ/GAMA/2007/Deferred_Shading_Tutorial_SBGAMES2005.pdf |title=Deferred Shading Tutorial |author=Fabio Policarpo and Francisco Fonseca }}
* {{cite web |url=http://www.guerrilla-games.com/publications/dr_kz2_rsx_dev07.pdf |title=Deferred Rendering in Killzone 2 |author=Michal Valient |month=July |year=2007 }}
* {{cite web |url=http://www.anandtech.com/show/5011/nvidiaea-posts-battlefield-3-graphics-tech-talk |title=Battlefield 3 Graphics Tech Talk |author=Johan Andersson |month=October |year=2011 }}
* {{cite web |url=http://www.disney.co.uk/cms_res/blackrockstudio/pdf/Rendering_Techniques_in_SplitSecond.pdf |title=Rendering Techniques in Split/Second |author=Jeremy Moore and David Jefferies |year=2009 }}
* {{cite web |url=http://www.crytek.com/sites/default/files/A_bit_more_deferred_-_CryEngine3.ppt |title="A bit more Deferred" - CryEngine 3 (PPT) |author=Martin Mittring }}
* {{cite web |url=http://http.developer.nvidia.com/GPUGems2/gpugems2_chapter09.html |title=Deferred Shading in S.T.A.L.K.E.R. |author=Oles Shishkovtsov }}
* {{cite web |url=http://http.developer.nvidia.com/GPUGems3/gpugems3_ch19.html |title=Deferred Shading in Tabula Rasa |author=Rusty Koonce }}
* {{cite web |url=http://aras-p.info/texts/CompactNormalStorage.html |title=Compact Normal Storage for small g-buffers |author=Aras Pranckevičius |date=4 August 2009 |accessdate=12 April 2012 }}
* {{cite web |url=http://the-witness.net/news/2010/03/graphics-tech-shadow-maps-part-1/ |title=Graphics Tech: Shadow Maps (part 1) |author=Jonathan Blow |date=3 March 2010 |accessdate=13 April 2012 }}
}}

[[Category:Shader development]]
[[Category:Core development projects]]

Howto:Design an autopilot

2012-05-13T23:29:55Z

Mcginnly: hundert > hundred - aglicising

This [[:Category:Howto|howto]] will guide you through the process of designing a stable and fully functional [[autopilot]] in [[FlightGear]]. We won't cover every single aspect, because there are hundreds of [[aircraft]] out there, with dozens of different autopilot configurations. However, after reading this howto, you should be able to be creative and create unexisting configurations.

For a technical reference of the used elements, check [[Autopilot Configuration Reference]].

== Pre-design ==
Why not make things slightly easier, before we start working on the autopilot? Since we will be updating the autopilot hundreds of times, making tiny adjustments each time, we don't want to reload FlightGear every time. Therefore, we assign an "reload autopilot configuration" action to a key on our keyboard. We've chosen Shift-F5, but it could be any key. Add the code to your <tt>[[$FG ROOT]]/keyboard.xml</tt> file.

<syntaxhighlight lang="xml">
<key n="261">
<name>F5</name>
<repeatable type="bool">true</repeatable>
<mod-shift>
<desc>Reload autopilot configuration</desc>
<binding>
<command>nasal</command>
<script>
fgcommand('reinit', props.Node.new({ subsystem: "xml-autopilot" }));
print("xml-autopilot reinitialized!");
</script>
</binding>
</mod-shift>
</key>
</syntaxhighlight>

== Creating the autopilot configuration file ==
Create an autopilot.xml file with the following content, somewhere inside your aircraft's root (eg. <tt>Aircraft/747-400/Systems/autopilot.xml</tt>).

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

</PropertyList>
</syntaxhighlight>

== A first controller: wing leveler ==
Let's start with a simple wing leveler that keeps your bank angle at zero (or any arbitrary value later). This could be a PID controller with the input from your current roll and a reference of zero. Output should go to your aileron-cmd. Start with:
* '''Kp:''' 0.00
* '''Ti:''' 100.00
* '''Td:''' 0.00

Be sure to add an <enable> element to easily enable/disable your controller if it gets unstable.

<syntaxhighlight lang="xml">
<pid-controller>
<name>Heading hold</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/heading</prop>
<value>wing-leveler</value>
</enable>
<input>
<prop>/orientation/roll-deg</prop>
</input>
<reference>0</reference>
<output>
<prop>/controls/flight/aileron</prop>
</output>
<config>
<Kp>0.00</Kp>
<Ti>100.0</Ti>
<Td>0.0</Td>
<u_min>-1.0</u_min>
<u_max>1.0</u_max>
</config>
</pid-controller>
</syntaxhighlight>

Since this is our first controller, we will give a short explenation of each part.

* '''Name:''' is only used for debugging.
* '''Debug:'''
* '''Enable:''' when the condition is true, the controller will be activated. In this case that will be when <tt>/autopilot/locks/heading=wing-leveler</tt>.
* '''Input:''' is the property that will be monitored by the controller. As our aim is to have a roll of zero degree, our input property is our roll orientation.
* '''Reference:''' most of the time this is a property, like input, but for this one we'll use a static value. The controller will try to get the value of the input to this reference-value.
* '''Output:''' the controller controls flight surfaces, in order to get the input value to the reference one.
* '''Config:''' thit is the tricky part. All these settings affect the behaviour (response time, surface deflection etc.) of the controller.
** '''u_min:''' the minimum output.
** '''u_max:''' the maximum output.

To get an idea of the Kp-value, you need to do a simple calclulation. The PID controller computes "reference - input". If you want wings leveled (zero roll) and your current bank angle is, say 30°, the result of "reference - input" is -30. If you think you need full aileron deflection to get from 30 degrees bank to zero in a reasonable time, you need a factor of 1/30=0.033, because aileron-cmd is in the range of -1 to +1. This is the approximate value for your Kp.

Now enter your aircraft and climb to cruise altitude and cruise speed. Bank your aircraft, to 15°-20°. Enable your controller (in our example that is by setting <tt>/autopilot/locks/heading=wing-leveler</tt>. [[Property Browser|Look here]] if you need help on setting properties.) and - nothing happens (because Kp is still zero). Set the value of Kp to 0.01 and hit Shift-F5 to reload your configuration and check what happens. Does the controller tries to level the wings or do things go worse? If the ailerons move in the wrong direction, you need to reverse the sign of Kp.

Once you found the correct sign for Kp, slowly (in steps as little as 0.005) increase the value of Kp to get a fast response. Don't forget to reload the config with Shift-F5 after every edit of your file. There is one pitfall that can drive you crazy: the PID-controller computes delta-values for its correction and it starts with the current setting of your aileron when it is enabled or reloaded. If you have your aileron set to -0.2 when you hit Shift-F5, the controller will apply its corrections to a value of -0.2 which will most certainly fail! Make sure that you have your flight controls neutral (press 5) when (re-)enabling PID-controllers!

You will achive good results by only setting Kp for a roll-computer as a wing-leveler. Slowly increase your Kp until it is just about to become unstable, than divide the current value of Kp by two and use that value. Try several configurations of your aircraft - slow flight, low altitude, fast cruise at higher altitudes. Fly turns with several bank angles, left and right. Whenever you enable your controller, it should level your wings within a few seconds and without bouncing back and forth.

Once you are satisfied with Kp - and not before! - decrease the value for Ti by dividing by a value of 10 and check the response of your controller. When it tends to become unstable, multiply it's Ti by two. Now you should have a fast and stable wing-leveler.

Finally (for the wing-leveler) you can turn it into a roll-hold by setting your target roll as a property for the reference. If you had <reference>0.0</reference>, bind your reference to a property (<reference>autopilot/settings/target-roll-deg</reference>) and your aircraft should roll to any value you set in target-roll-deg. The complete wing-leveler will look similar to the one below (though, the config values may vary and the reference might be replaced by a property).

<syntaxhighlight lang="xml">
<pid-controller>
<name>Heading hold</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/heading</prop>
<value>wing-leveler</value>
</enable>
<input>
<prop>/orientation/roll-deg</prop>
</input>
<reference>0</reference>
<output>
<prop>/controls/flight/aileron</prop>
</output>
<config>
<Kp>0.015</Kp>
<Ti>10.0</Ti>
<Td>0.0</Td>
<u_min>-1.0</u_min>
<u_max>1.0</u_max>
</config>
</pid-controller>
</syntaxhighlight>

This is the base for any lateral hold mode, so try to spend some time on it. It can take some hours if this is your first autopilot.

== Pitch hold ==
So, let's move over to a pitch hold. Our goal is to have a controller that maintains an arbitrary pich. The only difference to the wing leveler is that you are only interested in elevator position changes, not absolute values. To put it in other words: increase elevator for more pitch, decrease for less pitch and maintain elevator position if the pitch is right. This calls for a pid-controller, because it only computes offset values. And you will end up with a relative small value for Kp to avoid rapid imediate movements and a relative small value for Ti to have a greater effect over time.

Start again with a no-op pid-controller (Kp=0, Ti=100.000 and Td=0). Input is your current pitch (<tt>/orientation/pitch-deg</tt>), reference is a target-pitch property (you wouldn't want a constant zero here, <tt>/autopilot/settings/target-pitch-deg</tt>) and output goes to elevator-cmd (<tt>/autopilot/internal/elevator-cmd</tt>).

Again increase you Kp slowly and check each step in FlightGear. I'd expect something like -0.025 resulting in an instanteanous full elevator deflection on a 40 degrees pitch offset. Do not try too large values; it results in instable behaviour very quickly. Now, decrease the value of Ti, probably down to 10 or so. The smaller it gets, the faster the elevator moves and the easier it is to get an unstable loop. Again it is very likely that you won't need Td to get a stable controller.

== Simulating servos ==
Once you have this two axies running, you might want to think about simulating the slow movements of the servo or hydraulic motors that drive the control surfaces. You might have noticed, that the controls react rapidly when enabled which is unrealistic. In a [[Seneca]], the aileron servo takes 12 seconds to move from left to right. The elevator needs 26 seconds and the pitch trim takes 45 seconds for full travel.

There is a filter to simulate that behaviour, it's the noise-spike filter. Here is a sample with 25 seconds transition time from -1 to +1:

<syntaxhighlight lang="xml">
<filter>
<name>SERVO-DRIVER:elevator</name>
<debug>false</debug>
<feedback-if-disabled>true</feedback-if-disabled>
<enable>
<prop>/autopilot/locks/altitude</prop>
<value>pitch-hold</value>
</enable>
<input>/autopilot/internal/elevator-cmd</input>
<output>/controls/flight/elevator</output>
<type>noise-spike</type>
<max-rate-of-change>0.08</max-rate-of-change>
</filter>
</syntaxhighlight>

The formula for max-rate-of-change is (max-out - min-out)/transition-time. In our example (1--1)/25=2/25=0.08. Try it out, disable your pitch-hold controller and enable the servo-driver. Set your some/internal/elevator-cmd property to +1 and see your elevator moving to fully up or down within 12.5 seconds. Now set your property to -1 and it will take 25 seconds for the elevator to move to the other direction. The feedback-if-disabled property is needed, if this stage is driven from a pid-controller.

We said before that PID-controllers compute offsets to the curren value of it's output. If you disable the servo-driver from your A/P master switch, the value of your elevator is fed back to the internal value of the elevator-cmd so the pid-controller has a reasonable value to start from when it is enabled. Create servo drivers for elevator, aileron and the trim channels if you intend to use them. A good location for the internal driver properties is /autopilot/internal - but that is up to you.Now change your pitch and roll PID-controller so that they no longer directly drive the output properties but the internal properties. You might need to adjust the Kp and Ti values of the PID-controller because you introduced some lag with the driver. But you should end up with perfectly smooth operation of the two main channels.

Spend some time optimizing these pitch and roll channels, they will be used by all other modes and '''have''' to be stable in any case!

== A simple auto throttle ==
<syntaxhighlight lang="xml">
<pid-controller>
<name>Auto throttle</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/speed</prop>
<value>speed-with-throttle</value>
</enable>
<input>
<prop>/instruments/airspeed-indicator/indicated-speed-kt</prop>
</input>
<reference>
<prop>/autopilot/settings/target-speed-kt</prop>
</reference>
<output>
<prop>/autopilot/internal/throttle-cmd</prop>
</output>
<config>
<Kp>0.15</Kp>
<Ti>20.0</Ti>
<Td>0.00001</Td>
<u_min>0.0</u_min>
<u_max>1.0</u_max>
</config>
</pid-controller>
</syntaxhighlight>

And a filter, as our autopilot does not move the throttle levers up/down in split seconds (you can imagine how that would be potentially harmful to the flight crew). Depending on the number of engines of your aircraft, you might want to add more or delete some output properties.

<syntaxhighlight lang="xml">
<filter>
<name>SERVO-DRIVER:throttle</name>
<debug>false</debug>
<feedback-if-disabled>true</feedback-if-disabled>
<enable>
<prop>/autopilot/locks/speed</prop>
<value>speed-with-throttle</value>
</enable>
<input>/autopilot/internal/throttle-cmd</input>
<output>
<prop>/controls/engines/engine[0]/throttle</prop>
<prop>/controls/engines/engine[1]/throttle</prop>
<prop>/controls/engines/engine[2]/throttle</prop>
<prop>/controls/engines/engine[3]/throttle</prop>
</output>
<type>noise-spike</type>
<max-rate-of-change>0.1</max-rate-of-change>
</filter>
</syntaxhighlight>

== Vertical speed hold ==
Let's start with some thinking. For vertical-speed-hold, the controller has to compare your current rate-of-climb with your reference rate-of-climb. The ROC will be controlled by setting the pitch of the aircraft. We already have a pitch-hold controller, so we will set the target-pitch from our rate-of-climb controller. To not make our passengers barf when we enable our controller, it's important to set the target-pitch relative to our current pitch - which once again calls for a pid-controller (because of it's relative output).

To get the current pitch to a property which will be modified by a pid-controller later, we will now create a controller which serves as a so called "sample-and-hold" element. It simply copies the input property value to the output property value until it is disabled. The same property, that disables the sample-and-hold controller will enable the pid-controller that computes the pitch for the rate-of climb.Here is a sample-and-hold controller implemented with a gain-filter:

<syntaxhighlight lang="xml">
<filter>
<name>AP:Pitch sample and hold</name>
<debug>false</debug>
<enable>
<condition>
<not>
<property>/autopilot/locks/roc-lock</property>
</not>
</condition>
</enable>
<type>gain</type>
<gain>1.0</gain>
<input>/orientation/pitch-deg</input>
<output>/autopilot/internal/target-pitch-deg</output>
</filter>
</syntaxhighlight>

You probably have to adjust the property names. Note the condition element in the <enable> section - it has the same syntax as in the well-known <animation> elements. As long as the roc-lock property is false, input is copied to output. When it becomes true, the output property is no longer written by this filter and the next step can use this value as a start.

Right behind this filter, add a pid-controller using your current rate-of-climb as input and a target-rate-of-climb as reference. Enable this pid if your pitch sample-and-hold is not enabled (use the same condition, just remove the <not> elements). Your output goes to target-pitch-deg which should be the same property as the input of your pitch-hold controller. Use the same procedure to obtain the values for Kp and Ti. Kp will be small. The offset computes in feet per minute and 100fpm should result in a few degrees pitch change. Something like 0.01 or smaller will probably do. I'd expect Integrator time around 10-50. You should clamp the target-pitch to something less than +/- 90° - probably -10° and +20° or whatever is a reasonable value for your aircraft. It could look like this:

<syntaxhighlight lang="xml">
<pid-controller>
<name>Vertical speed pitch hold</name>
<debug>false</debug>
<enable>
<condition>
<property>/autopilot/locks/roc-lock</property>
</condition>
</enable>
<input>
<prop>/autopilot/internal/vert-speed-fpm</prop>
</input>
<reference>/autopilot/settings/vertical-speed-fpm</reference>
<output>
<prop>/autopilot/settings/target-pitch-deg</prop>
</output>
<config>
<Kp>0.001</Kp>
<Ti>10.0</Ti>
<Td>0.0</Td>
<u_min>-10.0</u_min>
<u_max>10.0</u_max>
</config>
</pid-controller>
</syntaxhighlight>

== Logic-controlled properties ==
These two new elements should give you a rate-of-climb hold mode for your autopilot. If you are not yet confused which controllers should be enabled in what mode, you will be very soon as we will add even more elements. If you are in the need for some logic-controlled properties, the autopilot can do this, too - no need for [[nasal]] helpers! There is a <logic> element that does all the magic:

<syntaxhighlight lang="xml">
<logic>
<name>Electrical Power</name>
<input>
<greater-than>
<property>systems/electrical/outputs/autopilot</property>
<value type="double">10.0</value>
</greater-than>
</input>
<output>autopilot/has-power</output>
<output>autopilot/servicable</output>
</logic>
</syntaxhighlight>

This creates two boolean properties: has-power and serviceable, and sets them to true if the electrical system provides more than 10.0 volts. You can build complex logic tables to drive your analog stages of the autopilot.

== Altitude hold ==
Now, that you have a ROC-hold mode, you most certainly want an altitude-hold with preselect. This will be a simple linear amplifier without any time dependencies. Again, you have to compare your current altitude with a reference value, but this time there will be no integrator involved. The bigger your offset from the reference altitude is, the bigger your rate of climb/descent should be. Let's assume, 1000ft offset should result in 500fpm ROC. The maximum rate of descent should be 1000fpm and the maximum rate of climb should be 2000fpm. Since there is no integrator involved, we use a simple gain filter to compute the rate of climb:

<syntaxhighlight lang="xml">
<filter>
<name>Target Rate of Climb Computer (ALT HOLD)</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/altitude</prop>
<value>altitude-hold</value>
</enable>
<type>gain</type>
<input>position/altitude-ft</input>
<reference>autopilot/settings/target-altitude-ft</reference>
<gain>-0.5</gain> 
<output>autopilot/internal/target-roc-fpm</output>
<min>-1000</min>
<max>2000</max>
</filter>
</syntaxhighlight>

If everything goes well, your chain of controllers for altitude hold looks something like this:
# '''Target Rate Of Climb Computer''' target-rate-of-climb = (reference-altitude - current-altitude) * 5
# '''Target Pitch Computer''' computes target-pitch-deg as a function of current-roc and target-roc
# '''Elevator Command Computer''' computes elevator-deflection as a function of current pitch and target pitch
# '''Elevator Servo Driver''' makes smooth movements of the elevator

This is nearly all for altitude-hold with altitude-preselect. You can add an altitude-sample-and-hold stage to add a "hold my current altitude" function.

== Heading hold ==
For heading hold, you build a two stage system. The first is a comparator comparing your selected heading and the indicated heading. 1. Stage, compute heading offset. Note the period element at the bottom, it normalizes the output into the periodic -180 to +180 range

<syntaxhighlight lang="xml">
<filter>
<name>Heading Offset Computer</name>
<debug>false</debug>
<type>gain</type>
<gain>1.0</gain>
<input>/autopilot/settings/heading-bug-deg</input>
<reference>/orientation/heading-magnetic-deg</reference>
<output>/autopilot/internal/heading-offset-deg</output>
<period>
<min>-180</min>
<max>180</max>
</period>
</filter>
</syntaxhighlight>

The second stage computes a bank angle from a heading offset. At least for smaller planes, a rule of thumb says "roll out at half the bank angle". If you fly a right hand turn at a bank angle of, say, 20° and want to end at a heading of 270°, you start your roll out at 20°/2 = 10° before your target heading. So you start rolling out at 280°. We turn this rule around and say our bank angle is twice the heading error but not more that 30° This results in a simple gain filter. You might want to make the target roll computer switchable with an enable element, otherwise it will overwrite your target-roll-deg at all times.

<syntaxhighlight lang="xml">
<filter>
<name>Target Roll Computer</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/heading</prop>
<value>dg-heading-hold</value>
</enable>
<type>gain</type>
<input>/autopilot/internal/heading-offset-deg</input>
<output>/autopilot/internal/target-roll-deg</output>
<gain>2.5</gain>
<min>-30.0</min>
<max>30.0</max>
</filter>
</syntaxhighlight>

Most aircraft have pilot selectable bank-limits. You can implement these by editing the min and max options to something like this:

<syntaxhighlight lang="xml">
...
<min>
<property>/autopilot/settings/bank-limit</property>
<scale>-1.0</scale>
</min>
<max>/autopilot/settings/bank-limit</max>
...
</syntaxhighlight>

This filter feeds your wing leveler which is already done, but it requires a little edit in the <enable> and <reference> parts in order to obtain a pilot-selectable roll:

<syntaxhighlight lang="xml">
...
<enable>
<prop>/autopilot/locks/heading</prop>
<value>dg-heading-hold</value>
</condition>
</enable>
...
<reference>
<prop>/autopilot/internal/target-roll-deg</prop>
</reference>
...
</syntaxhighlight>

You can also play with the min/max values to have a nice standard rate turn. The bank angle for the standard turn is a function of your true airspeed; you can build a controller calculating the correct bank angle and feed this value into min/max (which is a commen feature on airliners).

Decreasing the gain of 2.5 should help, if your roll-rate is too slow.

== NAV modes ==
In lateral nav mode, the primary goal of the autopilot is to intercept and maintain a certain ground track. This could be a VOR radial, a LOC course or back course or a GPS track. For most autopilots these are basically the same and it does not know anything about the source of the signal. Everything it knows is your current heading, your desired course and a course offset. And these are the properties, we need for our NAV hold mode.

Now, how does the autopilot knows which direction to steer? Lets assume you want to intercept the radial 270 of some VOR. VOR radials "radiate" away from the station, so the 270 radial points away from the station with a heading of 270degrees (which is west).Lets further assume you are somewhere south-west of the VOR station - this is between radial 180 and 270 - and you fly on a heading of 250 (this will become important later).

Now you have the most important facts at hand you need for navigation:
* Q1: Where am I?
* A1: South-west of the VOR
* Q2: Where would I want to be?
* A2: On radial 270 of the VOR

As a rule of thumb, interception of radials should occour at angles of 30° to 45°. Intercepting at angles lower than 30° takes ages to get you there, intercepting at greater than 45° angles might result in a very steep turn to not overshoot the radial. We pick 45° because I like this value most.Our next question to answer is
* Q3: Which way should I fly to get where I want to be?
* A3: To intercept the course of 270° at a 45° angle, fly 270°+45°=315°

Now that we know which way we should fly we can easily answer
* Q4: Which direction do I have to turn?
* A4: You are currently heading 250°. You want to fly heading 315°, so turn right by 65°.

That's basically all the magic about navigation. Now let's implement this in the autopilot. One part is already done: Q4/A4 is your heading-hold stage, so it's probably best to move backwards from that stage.

First, add a new, switchable input element to your heading offset computer. Just change this:
<syntaxhighlight lang="xml">
<filter>
<name>Heading Offset Computer</name>
<debug>false</debug>
<type>gain</type>
<gain>1.0</gain>
<input>/autopilot/settings/heading-bug-deg</input>
<reference>/orientation/heading-magnetic-deg</reference>
<output>/autopilot/internal/heading-offset-deg</output>
<period>
<min>-180</min>
<max>180</max>
</period>
</filter>
</syntaxhighlight>

to this (that is, adding the upper input part):
<syntaxhighlight lang="xml">
<filter>
<name>Heading Offset Computer</name>
<debug>false</debug>
<type>gain</type>
<gain>1.0</gain>
<input>
<condition>
<equals>
<property>/autopilot/locks/heading</property>
<value>nav1-hold</value>
</equals>
</condition>
<property>/autopilot/internal/intercept-heading-deg</property>
</input>
<input>/autopilot/settings/heading-bug-deg</input>
<reference>/orientation/heading-magnetic-deg</reference>
<output>/autopilot/internal/heading-offset-deg</output>
<period>
<min>-180</min>
<max>180</max>
</period>
</filter>
</syntaxhighlight>

Now, if /autopilot/locks/heading equals "nav1-hold", the heading offset computer uses the intercept-heading-deg property as the target heading to fly.For any other value, the old heading-bug value is used. You can already test, if it works. Use the property browser to set this stage to nav-hold and enter any arbitrary value into intercept-heading-deg. Your aircraft should turn to the entered heading on the shortest path. It is crucical that this mode is stable, so spend some time again and double check.

Next, we need to compute the intercept-heading-deg automatically. This is based on the offset from the desired course with a maximum intercept angle of 45°. The [[CDI]] is our friend, it tells us about our course offset, so we use that property in our stage feeding the Heading Offset Computer.

This is a very simple stage, it just substracts a course error (which we will compute in the next stage) from our selected course and normalizes the output into the [0..360] degree interval:

<syntaxhighlight lang="xml">
<filter>
<name>Intercept Heading Computer</name>
<debug>false</debug>
<type>gain</type>
<gain>1.0</gain>
<input>/autopilot/internal/selected-course</input>
<reference>/autopilot/internal/course-error-deg</reference>
<output>/autopilot/internal/intercept-heading-deg</output>
<period>
<min>0</min>
<max>360</max>
</period>
</filter>
</syntaxhighlight>

This stage only makes sense with a preceding one computing the course error from the cdi deflection. We want something that spits out 45 for a full CDI deflection and one might think of a <gain> filter to do this. But we also want an automatic wind correction in case of cross wind. For that we also need an integrator. Because we need to compute absolute values for the output, a pi-simple-controller is our choice here:

<syntaxhighlight lang="xml">
<pi-simple-controller>
<name>cdi-integrator</name>
<debug>false</debug>
<config>
<Kp>45.0</Kp>
<Ki>0.40</Ki>
</config>
<input>/autopilot/internal/cdi-deflection</input>
<output>/autopilot/internal/course-error-deg</output>
<min>-45.0</min>
<max>45.0</max>
</pi-simple-controller>
</syntaxhighlight>

It takes our CDI deflection and compares to zero (note the missing reference element which defaults to zero). The result is multiplied by Kp (45) and a value of 0.4° per second is added to the offset. The output is clipped to 45°.

You now have all stages, you need for the LNAV section. To compute the values in the correct order, they should be in the order
# cdi-integrator
# intercept heading computer
# heading offset computer

== Related content ==
{{Forum|46|Autopilot}}
* [[Autopilot Configuration Reference]]

[[Category:Aircraft enhancement|Autopilot Design an]]
[[Category:Howto|Autopilot Design an]]