Update layer effect documentation

Mainly formatting but also adding and editing some content.

Task-number: QT3DS-2055
Change-Id: Ie1ee9bfa12e40e66a1d49c79348265ea2ef10868
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

10 files changed, 229 insertions, 120 deletions

diff --git a/doc/src/03-studio/7-inspector-palette.qdoc b/doc/src/03-studio/7-inspector-palette.qdoc
index af2ebf33..392e788b 100644
--- a/doc/src/03-studio/7-inspector-palette.qdoc
+++ b/doc/src/03-studio/7-inspector-palette.qdoc
@@ -427,7 +427,7 @@ of the camera to be rendered. Aside from special clipping effects, you
 may need to adjust these values to more closely contain your content for
 better results with Ambient Occlusion, or with a layer effect that uses
 the depth buffer of the camera, such as the
-\l{Depth of Field}{Depth of Field effect}.}
+\l{{Depth of field HQ blur}}{Depth of Field effect}.}
 
 \list
 \li
diff --git a/doc/src/10-best-practices/80-effects.qdoc b/doc/src/10-best-practices/80-effects.qdoc
index 8a44ee15..6dad4eb4 100644
--- a/doc/src/10-best-practices/80-effects.qdoc
+++ b/doc/src/10-best-practices/80-effects.qdoc
@@ -69,7 +69,7 @@ lower in the scene graph will be applied before effects that are above them.
   \li
       \div {align="center"}
       \image depth-of-field-icon.png
-      \b {\l{Depth of field}}
+      \b {\l{Depth of field HQ blur}}
       \enddiv
   \li
       \div {align="center"}
diff --git a/doc/src/10-best-practices/depth-of-field-effect.qdoc b/doc/src/10-best-practices/depth-of-field-effect.qdoc
index 6e6c165d..b3a7d980 100644
--- a/doc/src/10-best-practices/depth-of-field-effect.qdoc
+++ b/doc/src/10-best-practices/depth-of-field-effect.qdoc
@@ -28,52 +28,64 @@
 
 /*!
 
-\title Depth of Field
+\title Depth of Field HQ Blur
 \page depth-of-field-effect.html
 \ingroup qt3dstudio-best-practices
 
-\section1 Using Depth of Field
+The depth of field HQ effect performs a gradient blur on regions of the
+image based on their deviation from a specified distance from the camera.
+
+In the image below, the effect is applied in the right picture. Notice that the cube and
+same-distance floor are in focus while the closer cone and farther sphere are blurred.
 
 \image Effects-DOF.png
 
-The \"Depth Of Field HQ Blur\" effect increasingly blurs regions of the
-image based on their deviation from a specified distance from the
-camera. (Notice that the cube and same-distance floor are in focus while
-the closer cone and farther sphere are blurred.)
+\section1 Properties
+
+\table
+  \header
+    \li Property
+    \li Description
+  \row
+    \li
+      Focus distance
+    \li
+      The distance from the camera where the content is in perfect focus.
+  \row
+    \li
+      Depth of field
+    \li
+      The distance around the \c{Focus Distance} where items are fully in focus. The focus then
+      fades away to fully blurred by the same distance on both the near and far sides.
+  \row
+    \li
+      Debug focus rendering
+    \li
+      Allows you to see exactly how the focus variables work.
+\endtable
+
+\section1 Usage
 
 For this effect to work well, you need to adjust the
-\c{Clipping Start} and \c{Clipping End} properties of the
-camera for the Layer to 'frame' the content. (You ideally want the
-largest possible value for \c{Start} and the smallest possible
-value for \c{End}.) After you do this you can use the properties of
-the effect in the Inspector palette to adjust the effect.
+\uicontrol{Clipping start} and \uicontrol{Clipping end} properties of the
+camera for the layer to frame the content. You ideally want the
+largest possible value for \uicontrol{Clipping start} and the smallest possible
+value for \uicontrol{Clipping end}. Next, adjust the properties of the effect for the desired
+result.
 
-\list
-\li
-  The \c{Focus Distance} property specifies the distance from the
-  camera where the content is in perfect focus.
-\li
-  The \c{Depth of Field} property specifies a the distance around
-  the \c{Focus Distance} where items are fully in focus. The focus
-  then fades away to fully blurred by the same distance on both the near
-  and far sides.
-\endlist
-For example, a \c{Focus Distance} of 100 and a
-\c{Depth of Field} of 20 means that everything that is between 90
-and 110 units away from the camera will be fully in focus, items at a
-distance of 70-90 and 110-130 units will experiencing variable blurring,
-and everything closer than 70 or farther than 130 will be fully blurred.
+For example, a \uicontrol{Focus distance} of 100 and a
+\uicontrol{Depth of field} of 20 means that everything that is between 90
+and 110 units away from the camera will be entirely in focus, items at a
+distance of 70-90 and 110-130 units will experience variable blurring,
+and everything closer than 70 or farther than 130 will be entirely blurred.
 
-To make it easier to set up this effect, turn on the
-\c{Debug Focus Rendering} checkbox for the effect:
-\image Effects-DOF-Debug.png
+To make it easier to set up this effect, enable \uicontrol{Debug focus rendering}. When enabled,
+the scene view switches to a mode showing the amount of blur to be applied. Anything completely
+fogged in white is entirely blurred, anything that is fully black is entirely in focus, and
+shades of grey represent varying amounts of blur in between. It is far easier to turn on this
+mode and adjust the values in the inspector palette until the content you want is bracketed,
+compared to performing distance calculations and entering numbers.
 
-When enabled the scene will switch to a mode showing the amount of blur
-to be applied. Anything completely fogged in white will be fully
-blurred, anything that is fully black will be fully in focus, and shades
-of grey represent varying amounts of blur in between. You will find it
-far easier to turn on this mode and just scrub the values in the
-Inspector palette until the content you want is bracketed, compared to
-performing distance calculations and entering numbers.
+\image Effects-DOF-Debug.png
 
 */
diff --git a/doc/src/10-best-practices/fxaa-effect.qdoc b/doc/src/10-best-practices/fxaa-effect.qdoc
index 51743000..1852d970 100644
--- a/doc/src/10-best-practices/fxaa-effect.qdoc
+++ b/doc/src/10-best-practices/fxaa-effect.qdoc
@@ -32,23 +32,38 @@
 \page fxaa-effect.html
 \ingroup qt3dstudio-best-practices
 
-\section1 Using FXAA
+The FXAA effect applies fast approximate anti-aliasing to the layer.
+FXAA is a high-speed anti-aliasing technique that removes some of the
+artifacts from the image without impacting performance as heavily as
+super-sampling would. In the image below, the effect is applied in the right picture.
 
 \image Effects-FXAA.png
 
-The \"FXAA\" effect applies Fast approXimate Anti-Aliasing to the layer.
-This is a high-speed anti-aliasing technique that removes some of the
-\"jaggies\" from the image without impacting performance as heavily as
-super-sampling would.
+\section1 Usage
 
-\list
-\li
-  Pros: easy fix for many aliasing problems; works with moving images
-  (unlike \l{best-practices-antialiasing.html#progressive-aa}{Progressive Anti-Aliasing}).
-\li
-  Cons: can blur and otherwise 'munge' fine text details present in the
-  layer; as a screen-space heuristic technique it can sometimes leave
-  sharp edges that ideally would be anti-aliased.
-\endlist
+\table
+  \header
+    \li
+      Pros
+    \li
+      Cons
+  \row
+    \li
+      \list
+        \li
+          Easy fix for many aliasing problems.
+        \li
+          Works with moving images
+         (unlike \l{best-practices-antialiasing.html#progressive-aa}{Progressive Anti-Aliasing}).
+      \endlist
+    \li
+      \list
+        \li
+          Can blur and distort fine text details.
+        \li
+          As a screen-space heuristic technique, it can sometimes leave
+          sharp edges that ideally would be anti-aliased.
+      \endlist
+\endtable
 
 */
diff --git a/doc/src/10-best-practices/gaussian-blur-effect.qdoc b/doc/src/10-best-practices/gaussian-blur-effect.qdoc
index 5c30f44e..1e5bbabc 100644
--- a/doc/src/10-best-practices/gaussian-blur-effect.qdoc
+++ b/doc/src/10-best-practices/gaussian-blur-effect.qdoc
@@ -32,15 +32,29 @@
 \page gaussian-blur-effect.html
 \ingroup qt3dstudio-best-practices
 
-\section1 Using Gaussian Blur
+The gaussian blur effect is simple to use and understand. It blurs all objects on the
+layer evenly.
+
+In the image below, the effect is applied in the right picture.
 
 \image Effects-GaussianBlur.png
 
-The \"Gaussian Blur\" effect is one of the simplest to use and
-understand. Drop it on a Layer and adjust the \c{Blurriness}
-property in the Inspector palette. In order to keep the effect
-performant large blur values will produce a mosaic result instead of
-smooth blurriness. Play with the slider for the value to find the best
-visual result for your needs.
+\section1 Properties
+
+\table
+  \header
+    \li Property
+    \li Description
+  \row
+    \li
+      Blurriness
+    \li
+      Level of blurriness.
+\endtable
+
+\section1 Usage
+
+To keep the effect performant, large blur values produce a mosaic result instead of
+smooth blurriness.
 
 */
diff --git a/doc/src/10-best-practices/hdr-bloom-tonemap-effect.qdoc b/doc/src/10-best-practices/hdr-bloom-tonemap-effect.qdoc
index 7349a453..f44a9a20 100644
--- a/doc/src/10-best-practices/hdr-bloom-tonemap-effect.qdoc
+++ b/doc/src/10-best-practices/hdr-bloom-tonemap-effect.qdoc
@@ -33,48 +33,65 @@
 \ingroup qt3dstudio-best-practices
 
 \target hdrbloomtonemap
-\section1 Using HDRBloomTonemap
 
-\image Effects-HDRBloomTonemap.png
-
-The \"HDRBloomTonemap\" effect provides two features:
+The HDR bloom tonemap effect provides two features:
 
-\list 1
+\list
 \li
   Adjust the gamma and exposure of the high-dynamic range rendered
-  content to achieve the image quality you want, and
+  content to achieve the image quality you want.
 \li
-  Apply an adjustable 'bloom' effect to very bright areas (like the sun
+  Apply an adjustable bloom effect to very bright areas (like the sun
   glinting off a car).
 \endlist
-When you add an HDRBloomTonemap effect to a layer, the following
-properties are available in the Inspector palette:
 
-\list
-\li
-  \b{Gamma} - this affects the non-linear curve of the lighting.
-  Higher values will increase the exposure of mid tones, lightening the
-  image (and decreasing the contrast). A value of \c{1.0} causes no
-  adjustment to the image.
-\li
-  \b{Exposure} - this is a linear multiplier on the lighting,
-  brightening or darkening the image overall. A value of \c{0.0}
-  causes no adjustment to the image.
-\li
-  \b{Bloom Threshold} - lighting greater than this value will
-  bloom. A value of \c{1.0} corresponds to white in the original
-  render result. Lowering this value will cause more areas of the
-  rendered scene to bloom; at a value of \c{0.0} everything in the
-  scene will bloom.
-\list
-\li
-  \e{Tip: to disable bloom and use only the tone mapping, set this to
-  a sufficiently high value, like \c{999}.}
-\endlist
-\li
-  \b{Bloom Falloff} - adjusts the amount of bloom. Lower values
+In the image below, the effect is applied in the right picture.
+
+\image Effects-HDRBloomTonemap.png
+
+\section1 Properties
+
+\table
+  \header
+    \li
+      Property
+    \li
+      Description
+  \row
+    \li
+      Gamma
+    \li
+      Affects the non-linear curve of the lighting.
+      Higher values increase the exposure of mid tones, lightening the
+      image (and decreasing the contrast). A value of \c{1.0} causes no
+      adjustment to the image.
+  \row
+    \li
+      Exposure
+    \li
+      A linear multiplier on the lighting,
+      brightening, or darkening the image overall. A value of \c{0.0}
+      causes no adjustment to the image.
+  \row
+    \li
+      Bloom threshold
+    \li
+      Lighting greater than this value blooms. A value of \c{1.0} corresponds to white
+      in the original render result. Lowering this value causes more areas of the
+      rendered scene to bloom; at a value of \c{0.0} everything in the
+      scene blooms.
+  \row
+    \li
+      Bloom falloff
+    \li
+      Adjusts the amount of bloom. Lower values
   result in stronger bloom effect; higher values make the effect more
   subtle.
-\endlist
+\endtable
+
+\section1 Usage
+
+To disable bloom and use only the tone mapping, set \uicontrol{Bloom falloff} to
+a sufficiently high value, like \c{999}.
 
 */
diff --git a/doc/src/10-best-practices/motion-blur-effect.qdoc b/doc/src/10-best-practices/motion-blur-effect.qdoc
index 2ea18623..534db3c9 100644
--- a/doc/src/10-best-practices/motion-blur-effect.qdoc
+++ b/doc/src/10-best-practices/motion-blur-effect.qdoc
@@ -32,16 +32,33 @@
 \page motion-blur-effect.html
 \ingroup qt3dstudio-best-practices
 
-\section1 Using Motion Blur
+The motion blur effect takes the image from the previous frame,
+blurs it, fades it by a specified amount, and draws this in the
+transparent areas of the layer. The result is that items moving
+over a transparent background leaves a ghost behind them.
 
 \image Effects-MotionBlur.png
 
-The \"Motion Blur\" effect takes the image from the previous frame,
-blurs it, fades it by a specified amount, and draws this \e{in the
-transparent areas of the layer}. The end result is that items moving
-over a transparent background will leave a ghost behind them.
+\section1 Properties
 
-The caveats for this effect are implicit in the above description:
+\table
+  \header
+    \li
+      Property
+    \li
+      Description
+  \row
+    \li
+      Fade Amount
+    \li
+      The amount the trail fades. A value of 0 does not fade the trail at all.
+      The trail is permanent. A value of 1 fades the trail completely, more or
+      less omitting the motion blur effect.
+\endtable
+
+\section1 Usage
+
+When using this effect, you should be aware of the following caveats:
 
 \list
 \li
@@ -50,12 +67,13 @@ The caveats for this effect are implicit in the above description:
   them.
 \li
   Only the transparent regions are drawn to. If a moving object passes
-  in front of another object on the same layer, there will be no motion
+  in front of another object on the same layer, there is no motion
   trail passing over the object.
 \endlist
-In the simple image shown above the blue ring is placed on a second
-Layer underneath the Layer with the motion blur effect applied. This
-both allows the 'needle' to leave a blur trail over top of the ring, and
+
+In the image shown above the blue ring is placed on a second
+layer underneath the layer with the motion blur effect applied. This
+both allows the needle to leave a blur trail over the ring, and
 also prevents the ring from having a blurry blue halo around it.
 
 */
diff --git a/doc/src/10-best-practices/tilt-shift-effect.qdoc b/doc/src/10-best-practices/tilt-shift-effect.qdoc
index d2c43fb7..ab0c748a 100644
--- a/doc/src/10-best-practices/tilt-shift-effect.qdoc
+++ b/doc/src/10-best-practices/tilt-shift-effect.qdoc
@@ -32,27 +32,60 @@
 \page tilt-shift-effect.html
 \ingroup qt3dstudio-best-practices
 
-\section1 Using Tilt Shift
+The tilt shift effect simulates depth of field in a simple and performant manner.
+Instead of blurring based on the depth buffer, it blurs everything except for a horizontal
+or vertical stripe on the layer.
 
 \image Effects-TiltShift.png
 
-The \"Tilt Shift\" effect simulates depth of field in a much simpler
-(and more performant) manner. Instead of blurring based on the depth
-buffer, it simply blurs everything except for horizontal stripe on the
-layer. The effect is controlled by the properties:
-
-\list
-\li
-  \c{Focus Position} - the vertical placement of the center of
-  effect (the 'focused region') on the screen, from top to bottom.
-\li
-  \c{Focus Width} - the vertical size of the in-focus region.
-\li
-  \c{Blur Amount} - how much the not-in-focus regions are blurred.
-\endlist
-As with the Depth of Field effect, this effect has a
-\c{Debug Rendering} option that you can enable to see where the
-blur will be applied to the Layer. (See above for further description.)
+\section1 Properties
+
+\table
+  \header
+    \li Property
+    \li Description
+  \row
+    \li
+      Focus position
+    \li
+      The vertical placement of the center of the focused area on the screen. A value
+      0.5 will put the center in the middle of the screen.
+  \row
+    \li
+      Focus width
+    \li
+      The height of the focused area.
+  \row
+    \li
+      Debug rendering
+    \li
+      Allows you to see exactly how the focus variables work.
+  \row
+    \li
+      Blur amount
+    \li
+      The amount of blur applied to the unfocused areas.
+  \row
+    \li
+      Vertical
+    \li
+      Makes the effect work vertically instead of horizontally.
+  \row
+    \li
+      Invert blur
+    \li
+      Inverts the blur so that the center is blurred while the other areas are sharp.
+\endtable
+
+\section1 Usage
+
+To make it easier to set up this effect, enable \uicontrol{Debug focus rendering}. When enabled,
+the scene view switches to a mode showing the amount of blur to be applied. Anything completely
+fogged in white is entirely blurred, anything that is fully black is entirely in focus, and
+shades of grey represent varying amounts of blur in between. It is far easier to turn on this
+mode and adjust the values in the inspector palette until the content you want is bracketed,
+compared to performing distance calculations and entering numbers.
+
 \image Effects-TiltShift-Debug.png
 
 */
diff --git a/doc/src/images/Effects-DOF-Debug.png b/doc/src/images/Effects-DOF-Debug.png
index b623935c..86714239 100644
--- a/doc/src/images/Effects-DOF-Debug.png
+++ b/doc/src/images/Effects-DOF-Debug.png
diff --git a/doc/src/images/Effects-TiltShift-Debug.png b/doc/src/images/Effects-TiltShift-Debug.png
index dfea44ef..c8253bae 100644
--- a/doc/src/images/Effects-TiltShift-Debug.png
+++ b/doc/src/images/Effects-TiltShift-Debug.png