343
edits
No edit summary |
|||
(46 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
{{forum|47|Effects & Shaders}} | {{forum|47|Effects & Shaders}} | ||
Line 9: | Line 5: | ||
|name = Compositor Framework | |name = Compositor Framework | ||
|started = 01/2018 (Available since FlightGear 2019.2) | |started = 01/2018 (Available since FlightGear 2019.2) | ||
|description = Dynamic rendering pipeline configured via the | |description = Dynamic rendering pipeline configured via the [[Property tree]] and [[PropertyList XML File|XML]] | ||
|status = Stable | |status = Stable (merged and actively maintained) | ||
|developers = Fernando García Liñán <ref>https://sourceforge.net/u/fgarlin/profile/</ref> | |developers = Fernando García Liñán <ref>https://sourceforge.net/u/fgarlin/profile/</ref> | ||
|changelog = https://sourceforge.net/u/fgarlin/profile/feed.rss | |changelog = https://sourceforge.net/u/fgarlin/profile/feed.rss | ||
Line 18: | Line 14: | ||
* {{fgdata file|Compositor}} | * {{fgdata file|Compositor}} | ||
}} | }} | ||
The '''Compositor''' aims to bring multi-pass rendering to FlightGear. It encapsulates a rendering pipeline and exposes its parameters to a [[Property Tree]] interface. At startup, FlightGear reads the pipeline definition file for each physical viewport defined on the [[Howto:Configure camera view windows|CameraGroup settings]]. If no Compositor file is specified for a physical camera, the one given by the <code>--compositor=</code> startup command will be used. If such startup option is not used either, FlightGear will look for a valid Compositor file in $FG_ROOT/Compositor/default.xml | The '''Compositor''' aims to bring multi-pass rendering to FlightGear. It encapsulates a rendering pipeline and exposes its parameters to a [[Property Tree]] interface. At startup, FlightGear reads the pipeline definition file for each physical viewport defined on the [[Howto:Configure camera view windows|CameraGroup settings]]. If no Compositor file is specified for a physical camera, the one given by the <code>--compositor=</code> startup command will be used. If such startup option is not used either, FlightGear will look for a valid Compositor file in $FG_ROOT/Compositor/default.xml | ||
The Compositor introduces a new dedicated fgdata directory for new/custom rendering pipelines: {{Fgdata file|Compositor}}. | The Compositor introduces a new dedicated fgdata directory for new/custom rendering pipelines: {{Fgdata file|Compositor}}. | ||
The framework is now included in the latest stable release ([[Changelog_2020.1|FlightGear v2020.1]]) as a separate binary. Developers are encouraged to test the Compositor with their personal projects and report any breakages. Also keep in mind that some features might not work/look as intended - see [[#Known Issues|Known Issues]]. | |||
== Background == | == Background == | ||
Line 77: | Line 77: | ||
== How to enable the Compositor == | == How to enable the Compositor == | ||
Currently the Compositor can only be enabled at compile time via the <code>-DENABLE_COMPOSITOR=ON</code> CMake flag in FlightGear. SimGear doesn't require any extra parameters. Once you have a binary with the Compositor enabled and you run it, you will be presented with the default rendering pipeline. At the time of writing, this is the low spec rendering pipeline. If you want to try the [[#ALS|ALS pipeline]], start FlightGear with the command line argument: <code>--compositor=Compositor | Currently, the Compositor can only be enabled at compile time via the <code>-DENABLE_COMPOSITOR=ON</code> CMake flag in FlightGear. | ||
SimGear doesn't require any extra parameters. | |||
On Linux, one can use <code>download_and_compile.sh --compositor</code> (see [[Scripted Compilation on Linux Debian/Ubuntu]]). | |||
Once you have a binary with the Compositor enabled and you run it, you will be presented with the default rendering pipeline. At the time of writing, this is the low spec rendering pipeline. If you want to try the [[#ALS|ALS pipeline]], start FlightGear with the command line argument: <code>--compositor=Compositor/als</code> | |||
If you want to enable shadows on all objects in the ALS pipeline use these options as a startup parameters (in QT GUI or in the commandline) <code>--prop:bool:/sim/rendering/als/shadows/enabled=true</code> and <code>--prop:int:/sim/rendering/als/shadows/sun-atlas-size=2048</code>. If you feel like the shadows are too low-quality (specially in the cockpit), increase the shadow resolution to 4096 or 8192 instead of 2048. | If you want to enable shadows on all objects in the ALS pipeline use these options as a startup parameters (in QT GUI or in the commandline) <code>--prop:bool:/sim/rendering/als/shadows/enabled=true</code> and <code>--prop:int:/sim/rendering/als/shadows/sun-atlas-size=2048</code>. If you feel like the shadows are too low-quality (specially in the cockpit), increase the shadow resolution to 4096 or 8192 instead of 2048. | ||
Line 185: | Line 190: | ||
* Unlike in Rembrandt, polygons facing the Sun are the ones used to generate the shadow map, so single sided surfaces and non-closed objects should be rendered correctly. | * Unlike in Rembrandt, polygons facing the Sun are the ones used to generate the shadow map, so single sided surfaces and non-closed objects should be rendered correctly. | ||
== | == Porting and developing Effects/Shaders == | ||
Effects can now have different implementations depending on the Compositor pipeline being used. For example, a grass Effect implemented in the ALS pipeline might have much more detail than the one in the low-spec pipeline. Still, they both implement the "look" of grass, so they share the same Effect file (grass.eff). | |||
The Compositor chooses which implementation of an Effect to render based on the <tt><scheme></tt> of the techniques. | |||
<syntaxhighlight lang="xml"> | |||
<technique n="15"> | |||
<scheme>als-lighting</scheme> | |||
[...] | |||
</technique> | |||
</syntaxhighlight> | |||
In this case the technique will be chosen if the Compositor pipeline <tt><scene></tt> pass uses the <tt>als-lighting</tt> Effect scheme. Consequently, porting an Effect to a pipeline will require knowing which Effect schemes it uses and writing a technique for each one. The only exception to this is the Default (Low-Spec) pipeline, which uses techniques with no scheme. | |||
Generally porting legacy Effects will require these steps: | |||
* Remove <tt>/sim/rendering/shaders/skydome</tt> from the ALS techniques and add the <tt>als-lighting</tt> scheme. | |||
* Remove Rembrandt techniques. | |||
* Use technique numbers from 0 to 9 for the Default pipeline techniques and 10 to 19 for the ALS pipeline. | |||
* Move the shaders to their correct directory. Now the <tt>$FG_ROOT/Shaders</tt> directory is subdivided into different folders for each pipeline. For example, shaders related to the ALS pipeline are located in <tt>$FG_ROOT/Shaders/ALS</tt>. | |||
To add features specific to a particular pipeline (like shadows in the ALS pipeline), see each pipeline's documentation below. | |||
=== ALS === | |||
==== Adding shadows ==== | |||
==== Rendering correct depth ==== | |||
The ALS pipeline uses a logarithmic depth buffer. This is accomplished by writing to <tt>gl_FragDepth</tt> in the fragment shader or by modifying <tt>gl_Position.z</tt> in the vertex shader. The second option is faster but doesn't work for polygons that intersect the near plane of the camera (e.g. terrain), so you should use it by default unless visual bugs appear. | |||
* '''1st option''' | |||
Add the following to the vertex shader: | |||
<syntaxhighlight lang="glsl"> | |||
uniform float fg_Fcoef; | |||
[...] | |||
gl_Position = ... | |||
gl_Position.z = (log2(max(1e-6, 1.0 + gl_Position.w)) * fg_Fcoef - 1.0) * gl_Position.w; | |||
</syntaxhighlight> | |||
* '''2nd option''' | |||
Add the following to the vertex shader: | |||
<syntaxhighlight lang="glsl"> | |||
varying float flogz; | |||
[...] | |||
gl_Position = ... | |||
flogz = 1.0 + gl_Position.w; | |||
</syntaxhighlight> | |||
And the following to the fragment shader: | |||
<syntaxhighlight lang="glsl"> | |||
uniform float fg_Fcoef; | |||
varying float flogz; | |||
[...] | |||
gl_FragColor = ... | |||
gl_FragDepth = log2(flogz) * fg_Fcoef * 0.5; | |||
</syntaxhighlight> | |||
== Pipeline technical notes == | |||
=== Low-Spec | === Default (Low-Spec) === | ||
A fixed function forward rendering pipeline mainly targeted to low spec systems. It imitates the classic forward pipeline used before multi-pass rendering was introduced by using two near/far cameras rendering directly to the screen. | A fixed function forward rendering pipeline mainly targeted to low spec systems. It imitates the classic forward pipeline used before multi-pass rendering was introduced by using two near/far cameras rendering directly to the screen. | ||
Line 194: | Line 255: | ||
=== ALS === | === ALS === | ||
{{See also|ALS technical notes}} | |||
The ALS pipeline tries to bring multipass rendering to the current ALS framework, effectively combining the best from ALS and Project Rembrandt. | The ALS pipeline tries to bring multipass rendering to the current ALS framework, effectively combining the best from ALS and Project Rembrandt. | ||
Line 203: | Line 265: | ||
* Improve the culling masks (simgear/scene/util/RenderConstants.hxx). The CASTSHADOW_BIT flag is present in almost every object in the scene graph. Turning this flag off for trees, random buildings and other geometry intensive objects improves framerates by a very considerable amount. Should the user be able to select which objects cast shadows? | * Improve the culling masks (simgear/scene/util/RenderConstants.hxx). The CASTSHADOW_BIT flag is present in almost every object in the scene graph. Turning this flag off for trees, random buildings and other geometry intensive objects improves framerates by a very considerable amount. Should the user be able to select which objects cast shadows? | ||
* Should the terrain cast shadows? The terrain is rarely steep enough to cast shadows. Apart from that, the terrain in FlightGear messes with automatic near/far computations for the shadow passes since the geometry is not tessellated enough. Also, the terrain LOD is not good enough to have decent cull times at far cascades. | * Should the terrain cast shadows? The terrain is rarely steep enough to cast shadows. Apart from that, the terrain in FlightGear messes with automatic near/far computations for the shadow passes since the geometry is not tessellated enough. Also, the terrain LOD is not good enough to have decent cull times at far cascades. | ||
* Adding a "internal only" shadow flag for aircraft developers. This allows farther shadow cascades to cull complex objects that are only visible in the nearest cascades. (Very important optimization for | * Adding a "internal only" shadow flag for aircraft developers. This allows farther shadow cascades to cull complex objects that are only visible in the nearest cascades. (Very important optimization for aircraft with complex cockpit geometry). | ||
* Vegetation shadows will be done by the "legacy" method currently in use. Shadow mapping on vegetation is much more expensive in terms of performance and the current algorithm does the job well enough. <ref>https://forum.flightgear.org/viewtopic.php?f=47&p=357606</ref> | * Vegetation shadows will be done by the "legacy" method currently in use. Shadow mapping on vegetation is much more expensive in terms of performance and the current algorithm does the job well enough. <ref>https://forum.flightgear.org/viewtopic.php?f=47&p=357606</ref> | ||
Line 450: | Line 512: | ||
! scope="row"| <tt>z-near, z-far</tt> | ! scope="row"| <tt>z-near, z-far</tt> | ||
| {{Yes}} | | {{Yes}} | ||
| | | float | ||
| | | 0.0 uses the value given by the CameraGroup | ||
| | | Sets a custom near and far values. Useful for implementing depth partition and limiting the depth range on cubemap passes | ||
|- | |- | ||
! scope="row"| <tt>cubemap-face</tt> | ! scope="row"| <tt>cubemap-face</tt> | ||
Line 459: | Line 521: | ||
| <tt>-1</tt> (don't use cubemap) | | <tt>-1</tt> (don't use cubemap) | ||
| Ignores the given view and projection matrices and uses a custom one that renders the scene as if it was seen from inside a cubemap looking towards the specified face | | Ignores the given view and projection matrices and uses a custom one that renders the scene as if it was seen from inside a cubemap looking towards the specified face | ||
|- | |||
! scope="row"| <tt>use-shadow-pass</tt> | |||
| {{Yes}} | |||
| string | |||
| Empty | |||
| Name of a shadow mapping pass. Exposes shadow mapping related uniforms to the shaders of the current pass | |||
|} | |||
Scene passes can also use the tag <code><clustered-shading></code> to enable clustered shading (lights). The following parameters are available: | |||
{| class="wikitable" style="text-align: center; font-size: 85%; width: auto; table-layout: fixed; | |||
! scope="col" | Parameter Name | |||
! scope="col" | Optional | |||
! scope="col" | Value | |||
! scope="col" | Default Value | |||
! scope="col" | Description | |||
|- | |||
! scope="row"| <tt>tile-size</tt> | |||
| {{Yes}} | |||
| int | |||
| 128 | |||
| Size of each clustered shading tile | |||
|- | |||
! scope="row"| <tt>num-threads</tt> | |||
| {{Yes}} | |||
| int | |||
| 1 | |||
| Number of threads to use during the light culling process. Keep in mind that a high thread count when there aren't many lights will worsen performance due to the thread creation overhead | |||
|- | |||
! scope="row"| <tt>depth-slices</tt> | |||
| {{Yes}} | |||
| int | |||
| 1 | |||
| Number of slices to partition the view frustum in the Z axis. Higher numbers will cull lights more aggressively, increasing performance if there are many lights further out that don't contribute much to the overall scene's lighting | |||
|} | |} | ||
Line 500: | Line 596: | ||
! scope="row"| <tt>near-m, far-m</tt> | ! scope="row"| <tt>near-m, far-m</tt> | ||
| {{No}} | | {{No}} | ||
| | | float (meters) | ||
| | | | ||
| They specify the depth range of the shadow map | | They specify the depth range of the shadow map | ||
Line 506: | Line 602: | ||
== TODO == | == TODO == | ||
{{See also|Post FlightGear 2020.2 LTS changes}} | |||
* Bring back distortion correction. | * Bring back distortion correction. | ||
* Some kind of versioning system to be able to make breaking changes in the future if/when the compositor is updated in any significant way, without people having to manually update their configs. | * Some kind of versioning system to be able to make breaking changes in the future if/when the compositor is updated in any significant way, without people having to manually update their configs. | ||
* | * Rework node masks ({{simgear file|simgear/scene/util/RenderConstants.hxx}}). Each node type should have its own node mask bit, e.g. trees should only have <tt>TREE_BIT</tt> enabled, the main aircraft should only have <tt>AIRCRAFT_BIT</tt> enabled etc. This allows the Compositor cameras to properly filter scene graph nodes based on the cull mask. Shadow cameras can then choose what geometry they render dynamically. | ||
* Automatically calculate light source attenuation based on radius and radius based on attenuation. | * Automatically calculate light source attenuation based on radius and radius based on attenuation. | ||
* Add | * Add clustered shading to every Effect as a separate technique. | ||
* Proper shader quality settings for both low-spec and ALS pipelines. | |||
* Launcher and UI: | |||
** [[Integrated Qt5 Launcher]] | |||
** [[About dialog]] | |||
** Rendering dialog | |||
* Separate [[Developing using CMake|cmake build target (binary)]] for a [http://download.flightgear.org/builds/nightly/ "preview" binary] with the [[Compositor]] enabled to get more testing/feedback and contributions from early-adopters <ref>https://sourceforge.net/p/flightgear/mailman/message/36977221/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36954518/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/36679177/</ref> <ref>https://sourceforge.net/p/flightgear/mailman/message/37000737/</ref> {{Progressbar|90}} | |||
== Known Issues == | == Known Issues == | ||
* Setting a buffer scale factor different from 1.0 and rendering to it might not scale the splash screen correctly. | * Setting a buffer scale factor different from 1.0 and rendering to it might not scale the splash screen correctly. | ||
* There is some kind of moiré pattern at certain sunlight angles (specially at dusk/dawn). Shadow acne. | |||
* There is some kind of moiré pattern at certain sunlight angles (specially at dusk/dawn). | |||
* Spotlights sometimes disappear at certain view angles. | * Spotlights sometimes disappear at certain view angles. | ||
* | * Some effects might not be ported to ALS completely. Feel free to play around with the shader settings to get something that works. | ||
* CRT effect as a default Effect. Look into reflect.eff | |||
* osgText doesn't work. See the 777 displays as well as some EC135 instruments. osgText doesn't use Effects so they are being rendered with incorrect depth. | |||
* Reloading shaders doesn't work. | |||
* Random buildings don't use correct depth. | |||
== References == | == References == | ||
Line 529: | Line 632: | ||
== Related content == | == Related content == | ||
=== Wiki articles === | === Wiki articles === | ||
* [[Canvas View Camera Element]] | |||
* [[CompositeViewer Support]] | |||
* [[Uniform Buffer Objects]] | * [[Uniform Buffer Objects]] | ||
* [[FlightGear CIGI Support (Common Image Generator Interface)]] | * [[FlightGear CIGI Support (Common Image Generator Interface)]] | ||
Line 537: | Line 641: | ||
* {{forum link|t=35095|text=Clustered Forward Rendering}} (12/2018) | * {{forum link|t=35095|text=Clustered Forward Rendering}} (12/2018) | ||
* {{forum link|t=33045|text=Getting started with RTT}} | * {{forum link|t=33045|text=Getting started with RTT}} | ||
[[Category:Core development projects]] | [[Category:Core development projects]] |
edits