From ad1395129e159fcd593db541dadc203d0eef37f4 Mon Sep 17 00:00:00 2001
From: Paul Olav Tvete <paul.tvete@qt.io>
Date: Wed, 21 Oct 2020 17:24:37 +0200
Subject: [PATCH] Update docs for built-in effects
Flesh out the docs. Use complete sentences. Clarify some things,
and fix some typos.
Change-Id: Ib4ea0660c8d367702c7580f15a16130c782ad34c
Reviewed-by: Andy Nichols <andy.nichols@qt.io>
---
.../quick3d/doc/src/qtquick3d-effects.qdoc | 212 +++++++++---------
1 file changed, 106 insertions(+), 106 deletions(-)
diff --git a/src/imports/quick3d/doc/src/qtquick3d-effects.qdoc b/src/imports/quick3d/doc/src/qtquick3d-effects.qdoc
index f3f9ddd28..f89ba55f9 100644
--- a/src/imports/quick3d/doc/src/qtquick3d-effects.qdoc
+++ b/src/imports/quick3d/doc/src/qtquick3d-effects.qdoc
@@ -26,7 +26,7 @@
****************************************************************************/
/*!
- \qmlmodule QtQuick3D.Effects 1.\QtMinorVersion
+ \qmlmodule QtQuick3D.Effects \QtVer
\title Qt Quick 3D Effects QML Types
\brief Provides QML types for the effects included in the Qt Quick 3D
effect library.
@@ -54,12 +54,12 @@
/*!
\qmlproperty vector3d AdditiveColorGradient::bottomColor
The color to be used at the bottom of the screen for the gradient.
- \c {Qt.vector3d(0.0, 0.0, 0.0)} by default.
+ The default is \c {Qt.vector3d(0.0, 0.0, 0.0)} (i.e. black).
*/
/*!
\qmlproperty vector3d AdditiveColorGradient::topColor
- The color to be used at the top of the screen for the gradient. \c {Qt.vector3d(1.0, 1.0, 1.0)}
- by default.
+ The color to be used at the top of the screen for the gradient. The default value
+ is \c {Qt.vector3d(1.0, 1.0, 1.0)} (i.e. white).
*/
/*!
@@ -69,12 +69,12 @@
\image effect_blur.png
- A simple one-pass blur.
+ This effect provides a simple one-pass blur. It is less expensive than GaussianBlur, but
+ does not give the same quality result.
*/
/*!
\qmlproperty real Blur::amount
- The strength of the blur. Sensible values are in the range \c {[0...0.01]}. \c {0.01} by
- default.
+ The strength of the blur. Sensible values are in the range \c {[0...0.01]}. The default value is \c {0.01}.
*/
/*!
@@ -93,16 +93,16 @@
/*!
\qmlproperty real BrushStrokes::brushLength
How far to offset the image with the brush. Sensible values are in the range \c {[0...3]}.
- \c {1} by default.
+ The default value is \c {1}.
*/
/*!
\qmlproperty real BrushStrokes::brushSize
- Scale of the brush. Smaller values yield larger sizes. Sensible values are in the range
- \c {[10...200]}. \c {100} by default.
+ The scale of the brush. Smaller values yield larger sizes. Sensible values are in the range
+ \c {[10...200]}. The default value is \c {100}.
*/
/*!
\qmlproperty real BrushStrokes::brushAngle
- Amount to rotate the brush noise texture. \c {45} by default.
+ The amount to rotate the brush noise texture, in degrees. The default value is \c {45}.
*/
/*!
@@ -112,23 +112,25 @@
\image effect_chromatic_aberration.png
- In real life, chromatic aberration is an optical phenomenon causing color fringes in high
- contrast areas. These color fringes are caused by different colors refracting at different
- angels splitting white light into a spectrum. This is called dispersion.
+ The ChromaticAberration effect simulates an imperfection of optical lenses. In real life,
+ chromatic aberration is an optical phenomenon causing color fringes in high contrast
+ areas. These color fringes are caused by different colors refracting at different angles
+ splitting white light into a spectrum. This is called dispersion.
*/
/*!
\qmlproperty TextureInput ChromaticAberration::maskTexture
- A grayscale texture to control position and strength of the effect. The effect is strongest in
+ A grayscale texture to control the position and strength of the effect. The effect is strongest in
white areas, and weakest in black areas.
- Default is a \l Texture with source \c {"maps/white.png"}.
+ The default is a \l Texture with source \c {"maps/white.png"}.
*/
/*!
\qmlproperty real ChromaticAberration::aberrationAmount
- Amount of aberration. A negative value inverses the effect. \c {50} by default.
+ The strength of the aberration effect. A negative value inverses the effect. The default value is \c {50}.
*/
/*!
\qmlproperty real ChromaticAberration::focusDepth
- Dispersion scales in relation to the distance from this value. \c {600} by default.
+ The distance to the focus plane. The dispersion scales in relation to the distance from this
+ value. The default value is \c {600}.
*/
/*!
@@ -138,24 +140,24 @@
\image effect_color_master.png
- The ColorMaster effect allows adjusting red, green, and blue separately, as well as overall
- saturation of the scene.
+ The ColorMaster effect adjusts the color balance and saturation of the scene.
*/
/*!
\qmlproperty real ColorMaster::redStrength
- The strength of red color. Range is \c {[0...2]}. \c {1} by default.
+ A multiplication factor for the red color channel. The range is \c {[0...2]}. The default value is \c {1}.
*/
/*!
\qmlproperty real ColorMaster::greenStrength
- The strength of green color. Range is \c {[0...2]}. \c {1.5} by default.
+ A multiplication factor for the green color channel. The range is \c {[0...2]}. The default value is \c {1.5}.
*/
/*!
\qmlproperty real ColorMaster::blueStrength
- The strength of blue color. Range is \c {[0...2]}. \c {1} by default.
+ A multiplication factor for the blue color channel. The range is \c {[0...2]}. The default value is \c {1}.
*/
/*!
\qmlproperty real ColorMaster::saturation
- The strength of the color. Range is \c {[-1...1]}. \c {0} by default.
+ The strength of all the colors in the scene. The range is \c {[-1...1]}, where \c {-1} is fully desaturated,
+ \c {0} is unmodified, and \c {1} is heavily oversaturated. The default value is \c {0}.
*/
/*!
@@ -184,18 +186,18 @@
*/
/*!
\qmlproperty real DepthOfFieldHQBlur::focusDistance
- The distance from the camera where the content is in perfect focus. \c {600} by default.
+ The distance from the camera where the content is in perfect focus. The default value is \c {600}.
*/
/*!
\qmlproperty real DepthOfFieldHQBlur::focusRange
The distance around the \l focusDistance 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.
- \c {100} by default.
+ The default value is \c {100}.
*/
/*!
\qmlproperty real DepthOfFieldHQBlur::blurAmount
The strength of blur when out of focus. Sensible values are in the range \c {[1...10]}.
- \c {4} by default.
+ The default value is \c {4}.
*/
/*!
@@ -205,12 +207,12 @@
\image effect_desaturate.png
- With the Desaturate effect, you can decrease the intensity of all colors in the scene.
+ The Desaturate effect allows decreasing the intensity of all colors in the scene.
*/
/*!
\qmlproperty real Desaturate::amount
- The amount of desaturation. Range is \c {[0...1]}, with \c 0 being fully saturated and \c 1
- being fully grayscale. \c {0.5} by default.
+ The strength of desaturation. The range is \c {[0...1]}, with \c 0 being fully saturated and \c 1
+ being fully grayscale. The default value is \c {0.5}.
*/
/*!
@@ -220,30 +222,29 @@
\image effect_distortion_ripple.png
- The DistortionRipple effect adds circular ripples, moving away from the center of the effect.
+ The DistortionRipple effect adds a wavelike distortion of circular ripples around a center point.
*/
/*!
\qmlproperty real DistortionRipple::radius
- The spread between ripples. Sensible values are in the range \c {[0...100]}. \c {100} by
- default.
+ How far the ripples extend from the center point. Sensible values are in the range \c {[0...100]}.
+ The default value is \c {100}.
*/
/*!
\qmlproperty real DistortionRipple::distortionWidth
- The width of a ripple. Sensible values are in the range \c {[2...100]}. \c {10} by default.
+ The width of a ripple. Sensible values are in the range \c {[2...100]}. The default value is \c {10}.
*/
/*!
\qmlproperty real DistortionRipple::distortionHeight
- The distortion amount. Sensible values are in the range \c {[0...100]}. \c {10} by default.
+ The distortion amount. Sensible values are in the range \c {[0...100]}. The default value is \c {10}.
*/
/*!
\qmlproperty real DistortionRipple::distortionPhase
The offset of each wave. Animate this property to see the waves move. Sensible values are in
- the range \c {[0...360]}. \c {0} by default.
+ the range \c {[0...360]}. The default value is \c {0}.
*/
/*!
\qmlproperty vector2d DistortionRipple::center
- The focus point of the distortion. \c {Qt.vector2d(0.5, 0.5)} (i.e. the center of the scene)
- by default.
+ The center point of the distortion. The default is \c {Qt.vector2d(0.5, 0.5)}, the center of the scene.
*/
/*!
@@ -257,16 +258,16 @@
*/
/*!
\qmlproperty real DistortionSphere::radius
- The area of distortion. Range is \c {[0...1]}. \c {0.25} by default.
+ How far the distortion extends from the center point. The range is \c {[0...1]}. The default value is \c {0.25}.
*/
/*!
\qmlproperty real DistortionSphere::distortionHeight
- The distortion amount. Range is \c {[-1...1}. \c {0.5} by default.
+ The distortion amount. The range is \c {[-1...1]}, where positive values distort towards the
+ camera, and negative values distort away from the camera. The default value is \c {0.5}.
*/
/*!
\qmlproperty vector2d DistortionSphere::center
- The focus point of the distortion. \c {Qt.vector2d(0.5, 0.5)} (i.e. the center of the scene)
- by default.
+ The center point of the distortion. The default is \c {Qt.vector2d(0.5, 0.5)}, the center of the scene.
*/
/*!
@@ -280,16 +281,15 @@
*/
/*!
\qmlproperty real DistortionSpiral::radius
- The area of distortion. Range is \c {[0...1]}. \c {0.25} by default.
+ How far the distortion extends from the center point. The range is \c {[0...1]}. The default value is \c {0.25}.
*/
/*!
\qmlproperty real DistortionSpiral::distortionStrength
- The distortion amount. Range is \c {[-10...10}. \c {1.0} by default.
+ The distortion amount. The range is \c {[-10...10]}. The default value is \c {1.0}.
*/
/*!
\qmlproperty vector2d DistortionSpiral::center
- The focus point of the distortion. \c {Qt.vector2d(0.5, 0.5)} (i.e. the center of the scene)
- by default.
+ The center point of the distortion. The default is \c {Qt.vector2d(0.5, 0.5)}, the center of the scene.
*/
/*!
@@ -304,7 +304,7 @@
*/
/*!
\qmlproperty real EdgeDetect::edgeStrength
- The strength of the edge highlighting. Range is \c {[0...1]}. \c {0.5} by default.
+ The strength of the edge highlighting. The range is \c {[0...1]}. The default value is \c {0.5}.
*/
/*!
@@ -320,8 +320,7 @@
*/
/*!
\qmlproperty real Emboss::amount
- The strength of the emboss effect. Sensible values are in the range \c {[0...0.01]}. \c {0.003}
- by default.
+ The strength of the emboss effect. Sensible values are in the range \c {[0...0.01]}. The default value is \c {0.003}.
*/
/*!
@@ -335,11 +334,11 @@
*/
/*!
\qmlproperty bool Flip::flipHorizontally
- Set to flip the scene horizontally. \c {true} by default.
+ This property determines whether the scene is flipped horizontally. The default value is \c {true}.
*/
/*!
\qmlproperty bool Flip::flipVertically
- Set to flip the scene vertically. \c {true} by default.
+ This property determines whether the scene is flipped vertically. The default value is \c {true}.
*/
/*!
@@ -387,13 +386,12 @@
\image effect_gaussian_blur.png
- The GaussianBlur effect is simple to use and understand. It blurs all objects in the
- scene evenly. To keep the effect performant, large blur \l amount produces a mosaic result
- instead of smooth blurriness.
+ The GaussianBlur effect blurs all objects in the scene evenly. To keep the effect performant,
+ a large blur \l amount will not produce a perfectly smooth blur, but rather a mosaic result.
*/
/*!
\qmlproperty real GaussianBlur::amount
- The strength of the blur. Sensible values are in the range \c {[0...10]}. \c {2} by default.
+ The strength of the blur. Sensible values are in the range \c {[0...10]}. The default value is \c {2}.
*/
/*!
@@ -407,10 +405,10 @@
\list
\li
- Adjust the gamma and exposure of the high-dynamic range rendered
+ Adjusting the gamma and exposure of the high-dynamic range rendered
content to achieve the image quality you want.
\li
- Apply an adjustable bloom effect to very bright areas (like the sun
+ Applying an adjustable bloom effect to bright areas (like the sun
glinting off a car).
\endlist
*/
@@ -418,33 +416,33 @@
\qmlproperty real HDRBloomTonemap::gamma
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. Sensible values are in the range \c {[0.1...4]}. \c {1} by default.
+ adjustment to the image. Sensible values are in the range \c {[0.1...4]}. The default value is \c {1}.
*/
/*!
\qmlproperty real HDRBloomTonemap::exposure
- A linear multiplier on the lighting, brightening, or darkening the image overall. A value of
- \c{0.0} causes no adjustment to the image. Range is \c {[-9...9]}. \c {0} by default.
+ Sets a linear multiplier on the lighting, brightening, or darkening the image overall. A value of
+ \c{0.0} causes no adjustment to the image. The range is \c {[-9...9]}. The default value is \c {0}.
*/
/*!
\qmlproperty real HDRBloomTonemap::bloomThreshold
- 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. Range is \c {[0...1]}. \c {1} by default.
+ Sets the threshold for the bloom effect. Any part of the scene brighter than this value will bloom.
+ A value of \c{1.0} corresponds to white. Lowering this value causes more areas of the rendered scene to bloom.
+ At a value of \c{0.0} everything in the scene blooms. The range is \c {[0...1]}. The default value is \c {1}.
*/
/*!
\qmlproperty real HDRBloomTonemap::blurFalloff
- Adjusts the amount of bloom. Lower values result in stronger bloom effect, and higher values
- make the effect more subtle. Range is \c {[0...10]}. \c {0} by default.
+ Adjusts the amount of bloom. Lower values result in a stronger bloom effect, and higher values
+ make the effect more subtle. The range is \c {[0...10]}. The default value is \c {0}.
*/
/*!
\qmlproperty real HDRBloomTonemap::tonemappingLerp
- Strength of the overall bloom effect. There is usually no need to adjust this. Range is
- \c {[0...1]}, with \c 0 being no blur and \c 1 being full bloom. \c {1} by default.
+ Specifies the strength of the overall bloom effect. There is usually no need to adjust this. The range is
+ \c {[0...1]}, with \c 0 being no blur and \c 1 being full bloom. The default value is \c {1}.
*/
/*!
\qmlproperty real HDRBloomTonemap::channelThreshold
- The white point for the image. There is usually no need to adjust this. Range is \c {[0...1]}.
- \c {1} by default.
+ Specifies the white point for the image. There is usually no need to adjust this. The range is \c {[0...1]}.
+ The default value is \c {1}.
*/
/*!
@@ -454,20 +452,20 @@
\image effect_motion_blur.png
- The MotionBlur effect creates an apparent streaking for rapidly moving objects in the scene.
+ The MotionBlur effect creates a trailing streak for rapidly moving objects in the scene.
\note The \l {SceneEnvironment::backgroundMode}{background mode} must be
\c {SceneEnvironment.Transparent} for MotionBlur to work.
*/
/*!
\qmlproperty real MotionBlur::fadeAmount
- Fade speed of the trail. Range is \c {[0...1]}, with \c 0 meaning the object trail persists
- indefinitely and \c 1 meaning the object trail fades out immediately. \c {0.25} by default.
+ How fast the trail fades. The range is \c {[0...1]}, with \c 0 meaning that the object trail persists
+ indefinitely, and \c 1 meaning that the object trail fades out immediately. The default value is \c {0.25}.
*/
/*!
\qmlproperty real MotionBlur::blurQuality
- The quality of the blur. Increasing quality will have impact on performance.
- Range is \c {[0...1]}. \c {0.25} by default.
+ The quality of the blur used to create the trail. Increasing quality will have impact on performance.
+ The range is \c {[0...1]}. The default value is \c {0.25}.
*/
/*!
@@ -483,20 +481,20 @@
*/
/*!
\qmlproperty TextureInput Scatter::noiseSample
- The scatter noise texture map. Default is a \l Texture with source \c {"maps/brushnoise.png"}.
+ The scatter noise texture map. The default is a \l Texture with source \c {"maps/brushnoise.png"}.
*/
/*!
\qmlproperty real Scatter::amount
- Determines how much to scatter. Range is \c {[0...127]}. \c {10} by default.
+ Determines how much to scatter. The range is \c {[0...127]}. The default value is \c {10}.
*/
/*!
\qmlproperty int Scatter::direction
The direction in which to scatter the pixels. Set to \c 0 for both horizontal and vertical,
- \c 1 for horizontal, and \c 2 for vertical. \c 0 by default.
+ \c 1 for horizontal, and \c 2 for vertical. The default value is \c 0.
*/
/*!
\qmlproperty bool Scatter::randomize
- Specifies whether scattering changes at each frame or not. \c {true} by default.
+ Specifies whether the scattering pattern changes for each frame. The default value is \c {true}.
*/
/*!
@@ -511,48 +509,49 @@
*/
/*!
\qmlproperty real SCurveTonemap::shoulderSlope
- S-Curve shoulder slope. Shoulder defines where highlights lose contrast.
- Range is \c {[0...3]}. \c {1} by default.
+ Sets the S-Curve shoulder slope. The shoulder defines where highlights lose contrast.
+ The range is \c {[0...3]}. The default value is \c {1}.
*/
/*!
\qmlproperty real SCurveTonemap::shoulderEmphasis
- Range is \c {[-1...1]}. \c {0} by default.
+ The range is \c {[-1...1]}. The default value is \c {0}.
*/
/*!
\qmlproperty real SCurveTonemap::toeSlope
- S-Curve toe slope. Toe defines where shadows lose contrast. Range is \c {[0...3]}.
- \c {1} by default.
+ Sets the S-Curve toe slope. The toe defines where shadows lose contrast. The range is \c {[0...3]}.
+ The default value is \c {1}.
*/
/*!
\qmlproperty real SCurveTonemap::toeEmphasis
- Range is \c {[-1...1]}. \c {0} by default.
+ The range is \c {[-1...1]}. The default value is \c {0}.
*/
/*!
\qmlproperty real SCurveTonemap::contrastBoost
- Enhance or reduce the overall contrast of the tonemap. Range is \c {[-1...2]}. \c {0} by
- default.
+ Enhances or reduces the overall contrast of the tonemap. The range is \c {[-1...2]}. The default value is \c {0}.
*/
/*!
\qmlproperty real SCurveTonemap::saturationLevel
- The overall saturation level of the tonemap. Range is \c {[0...2]}, with \c 0 being fully
- grayscale and \c being very oversaturated. \c {1} by default.
+ Sets the overall saturation level of the tonemap. The range is \c {[0...2]}, with \c 0 being fully
+ grayscale and \c 2 being very oversaturated. The default value is \c {1}.
*/
/*!
\qmlproperty real SCurveTonemap::gammaValue
- The gamma of the tonemap. Sensible values are in the range \c {[0.1...8]}. \c {2.2} by default.
+ Sets the gamma of the tonemap. Sensible values are in the range \c {[0.1...8]}. The default value is \c {2.2}.
*/
/*!
\qmlproperty bool SCurveTonemap::useExposure
- Specifies if \l exposureValue or \l whitePoint will be used for luminance calculations.
- \c {false} by default.
+ Makes the effect use \l whitePoint instead of \l exposureValue for luminance calculations.
+ The default value is \c {false}.
*/
/*!
\qmlproperty real SCurveTonemap::whitePoint
- Range is \c {[0.01...128]}. \c {1} by default.
+ Sets the white point of the tonemap. This value is only used if \l useExposure is \c {false}.
+ The range is \c {[0.01...128]}. The default value is \c {1}.
*/
/*!
\qmlproperty real SCurveTonemap::exposureValue
- Range is \c {[0.01...16]}. \c {1} by default.
+ Specifies the exposure of the tonemap. This value is only used if \l useExposure is \c {true}.
+ The range is \c {[0.01...16]}. The default value is \c {1}.
*/
/*!
@@ -563,33 +562,34 @@
\image effect_tilt_shift.png
The TiltShift 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.
+ Instead of blurring based on the depth buffer, it blurs everything outside a horizontal
+ or vertical strip of the scene.
\sa DepthOfFieldHQBlur
*/
/*!
\qmlproperty real TiltShift::focusPosition
- Placement of the focus bar in normalized coordinates. Range is \c {[0...1]}. \c {0.5} by
- default.
+ The placement of the focus bar in normalized coordinates. The range is \c {[0...1]}.
+ The default value is \c {0.5}, corresponding to the middle of the scene.
*/
/*!
\qmlproperty real TiltShift::focusWidth
- Objects within this normalized range of \l focusPosition will be in focus.
- Range is \c {[0...1]}. \c {0.2} by default.
+ Specifies the width of the in-focus area in normalized coordinates.
+ Objects within this range of \l focusPosition will be in focus.
+ The range is \c {[0...1]}. The default value is \c {0.2}.
*/
/*!
\qmlproperty real TiltShift::blurAmount
- The amount of blur. Amounts above 4 may cause artifacts. Range is \c {[0...10]}. \c {4} by
- default.
+ Specifies the strength of the blur effect. Values above 4 may cause artifacts.
+ The range is \c {[0...10]}. The default value is \c {4}.
*/
/*!
\qmlproperty bool TiltShift::isVertical
- Makes the effect work vertically instead of horizontally. \c {false} by default.
+ Makes the effect work vertically instead of horizontally. The default value is \c {false}.
*/
/*!
\qmlproperty bool TiltShift::isInverted
- Inverts the blur area, so the center is blurred instead. \c {false} by default.
+ Inverts the blur area, so the center is blurred instead. The default value is \c {false}.
*/
/*!
@@ -601,13 +601,13 @@
*/
/*!
\qmlproperty real Vignette::vignetteStrength
- Strength of the vignetting. Range is \c {[0...15]}. \c {15} by default.
+ Specifies the strength of the vignetting. The range is \c {[0...15]}. The default value is \c {15}.
*/
/*!
\qmlproperty real Vignette::vignetteRadius
- Size of the vignetting. Range is \c {[0...5]}. \c {0.35} by default.
+ Specifies the size of the vignetting. The range is \c {[0...5]}. The default value is \c {0.35}.
*/
/*!
\qmlproperty vector3d Vignette::vignetteColor
- The color to use for the vignetting. \c {Qt.vector3d(0.5, 0.5, 0.5)} by default.
+ Sets the color to use for the vignetting. The default value is \c {Qt.vector3d(0.5, 0.5, 0.5)}.
*/
--
GitLab