1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \qmlmodule QtQuick3D.Helpers
6 \title Qt Quick 3D Helpers QML Types
7 \brief Module containing helpers for creating applications using Qt Quick 3D.
9 This module provides helper types that make it easier to develop applications
10 using \l{Qt Quick 3D}.
15 \inqmlmodule QtQuick3D.Helpers
17 \brief Visual helper for showing the 3 axes and a grid in a 3D scene.
21 The X axis is red, the Y axis is green, and the Z axis is blue.
23 The example scene here has a Sphere at position \c{(0, 0, 0)} and an
24 AxisHelper object. With the WasdController helper one can conveniently
34 position: Qt.vector3d(0, 0, 600)
38 position: Qt.vector3d(-500, 500, -100)
39 color: Qt.rgba(0.4, 0.2, 0.6, 1.0)
40 ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
45 materials: [ DefaultMaterial { } ]
53 controlledObject: camera
58/*! \qmlproperty color AxisHelper::gridColor
59 Specifies the color of the grid. The default value is \c{Qt.rgba(0.8, 0.8, 0.8, 1)}.
61/*! \qmlproperty real AxisHelper::gridOpacity
62 Specifies the opacity of the grid. The default value is 0.5.
64/*! \qmlproperty bool AxisHelper::enableXZGrid
65 Enables the grid on XZ plane. The default value is true.
67/*! \qmlproperty bool AxisHelper::enableXYGrid
68 Enables the grid on XY plane. The default value is false.
70/*! \qmlproperty bool AxisHelper::enableYZGrid
71 Enables the grid on YZ plane. The default value is false.
73/*! \qmlproperty bool AxisHelper::enableAxisLines
74 Enables showing the axis lines. The default value is true.
78 \qmltype WasdController
79 \inqmlmodule QtQuick3D.Helpers
81 \brief Control node position and orientation with keys and mouse.
83 This helper allows the user to control a node using W, A, S, D, the arrow
84 keys, and the mouse. Usually the controlled node is a Camera, specified in
85 the controlledObject property.
87 Adding a WasdController can be highly useful both in applications that wish
88 to provide a standard way of navigating the scene, and also as a temporary
89 measure during development and troubleshooting, as it allows inspecting the
90 scene at run time via familiar keyboard and mouse navigation.
92 The key bindings are as follows:
95 \li \c W or \c up - go forward
96 \li \c S or \c down - go backward
97 \li \c A or \c left - strafe left
98 \li \c D or \c right - strafe right
99 \li \c R or \c {page up} - move up
100 \li \c F or \c {page down} - move down
101 \li \c shift together with other keys - move faster, depending on \l shiftSpeed
104 The following snippet shows how a WasdController object can be added. By
105 default both key and mouse based navigation is active, so in most cases
106 there is no further configuration needed:
114 position: Qt.vector3d(0, 0, 600)
120 controlledObject: camera
125/*! \qmlproperty QtQuick3D::Node WasdController::controlledObject
126 Specifies the node to control. This is typically a Camera object.
128/*! \qmlproperty real WasdController::speed
129 Specifies the speed of navigation.
131/*! \qmlproperty real WasdController::shiftSpeed
132 Specifies the speed multiplier that is active when the shift key is pressed.
134/*! \qmlproperty real WasdController::forwardSpeed
135 Specifies the speed of navigation when the forward key is pressed.
137/*! \qmlproperty real WasdController::backSpeed
138 Specifies the speed of navigation when the back key is pressed.
140/*! \qmlproperty real WasdController::rightSpeed
141 Specifies the speed of navigation when the right key is pressed.
143/*! \qmlproperty real WasdController::leftSpeed
144 Specifies the speed of navigation when the left key is pressed.
146/*! \qmlproperty real WasdController::upSpeed
147 Specifies the speed of navigation when the up key is pressed.
149/*! \qmlproperty real WasdController::downSpeed
150 Specifies the speed of navigation when the down key is pressed.
152/*! \qmlproperty real WasdController::xSpeed
153 Specifies the speed of navigation when the mouse is moved along the X axis.
155/*! \qmlproperty real WasdController::ySpeed
156 Specifies the speed of navigation when the mouse is moved along the Y axis.
158/*! \qmlproperty bool WasdController::xInvert
159 Inverts the x-axis controls. The default value is false.
161/*! \qmlproperty bool WasdController::yInvert
162 Inverts the y-axis controls. The default value is true.
164/*! \qmlproperty bool WasdController::mouseEnabled
165 Enables mouse controls. The default value is true.
167/*! \qmlproperty bool WasdController::keysEnabled
168 Enables key controls. The default value is true.
170/*! \qmlproperty bool WasdController::inputsNeedProcessing
171 This property is true when there are inputs needing processing.
174/*! \qmlproperty enumeration WasdController::acceptedButtons
175 Specifies the buttons accepted by the controller.
176 \sa DragHandler, MultiPointHandler
181 \inqmlmodule QtQuick3D.Helpers
183 \brief View to show rendering statistics and perform debug and developer actions.
185 This helper allows viewing render performance statistics of a View3D. It
186 shows the FPS, sync and render times. In addition, it can also show
187 detailed statistics about draw calls, render passes, and the textures and
188 meshes used by the scene's assets. The showing of such extended information
189 is controlled by the resourceDetailsVisible property, which defaults to
192 For example, the following snippet shows how a DebugView can be added that
193 shows its information in the top-left corner of the Qt Quick scene:
202 position: Qt.vector3d(0, 0, 600)
208 resourceDetailsVisible: true
212 In addition, the \c Tools section allows performing actions such as turning
213 on wireframe rendering, or visualizing various aspects of the material.
216/*! \qmlproperty var DebugView::source
217 Specifies the source View3D to show the statistics from.
220/*! \qmlproperty bool DebugView::resourceDetailsVisible
222 Indicates whether the additional fields with detailed render pass, mesh,
223 texture, and other resource statistics should be shown by default.
225 The default value is false, which means only CPU timings from the last
226 rendered frame will be shown, unless the user interactively enables
227 additional data via the on-screen checkbox. Change the value to true to make
228 more information visible by default. This includes render pass details and
229 the active assets for the last rendered frame.
233 \qmltype OrbitCameraController
234 \inqmlmodule QtQuick3D.Helpers
236 \brief Camera Controller which rotates around an origin.
238 This helper provides a way to rotate a camera around an origin. To function
239 OrbitCameraController accepts a Node as the origin, and a Camera object
240 which should be a child of the originNode to control. By only adjusting the z
241 position of the child camera relative to the parent origin it has the effect
242 of moving the camera nearer or farther from the target origin. By applying
243 a rotation to the origin node, the child camera will be orbited around the
246 The OrbitCameraController item itself is a 2D item that accepts input events
247 so whatever it's size and position will be where input events are accepted.
248 To zoom either use the scroll wheel of the mouse or perform a pinch gesture.
249 To rotate click or touch and drag the area. To pan, hold control and drag
250 the area. Panning will change the position of the origin node. It is also
251 possible to perform a panning gesture by performing a two finger drag.
263 OrbitCameraController {
273/*! \qmlproperty QtQuick3D::Node OrbitCameraController::origin
274 Specifies the origin node to control. This is a required property and should
275 be the parent of the \l camera
277/*! \qmlproperty QtQuick3D::Camera OrbitCameraController::camera
278 Specifies the camera node to control. This is a required property and should
279 be a child of the \l origin node.
281/*! \qmlproperty real OrbitCameraController::xSpeed
282 Specifies the speed of navigation when the mouse is moved along the X axis.
284/*! \qmlproperty real OrbitCameraController::ySpeed
285 Specifies the speed of navigation when the mouse is moved along the Y axis.
287/*! \qmlproperty bool OrbitCameraController::xInvert
288 Inverts the x-axis controls. The default value is false.
290/*! \qmlproperty bool OrbitCameraController::yInvert
291 Inverts the y-axis controls. The default value is true.
293/*! \qmlproperty bool OrbitCameraController::mouseEnabled
294 Enables mouse controls. The default value is true.
296/*! \qmlproperty bool OrbitCameraController::panEnabled
297 Enables panning controls. The default value is true.
302 \inqmlmodule QtQuick3D.Helpers
304 \brief Manager that handles level of detail visibility changes.
306 This helper provides a way to handle level of detail changes. It works
307 by changing the visibility of its child nodes based on the distance
308 to the camera. The thresholds are determined by the user using the
309 distances list. The first distance is the threshold when the manager
310 changes from showing the first child and the second child etc. The first
311 child should be the most detailed one as it is shown when the camera is
312 close. If fadeDistance is set, the manager cross-fades between models by
313 changing their opacity. Fading only works with model nodes.
330/*! \qmlproperty QtQuick3D::Camera LodManager::camera
331 Specifies the camera from which the distance to the child nodes is calculated.
334/*! \qmlproperty list LodManager::distances
335 Specifies the thresholds when the detail level changes. The first number
336 is the distance when the first node changes to the second one, etc.
339/*! \qmlproperty real LodManager::fadeDistance
340 Specifies the distance at which the cross-fade between the detail levels
345 \qmltype ExtendedSceneEnvironment
346 \inqmlmodule QtQuick3D.Helpers
347 \inherits SceneEnvironment
348 \brief A SceneEnvironment providing commonly used rendering effects.
351 The \c ExtendedSceneEnvironment is an extension of QtQuick3D's \l
352 SceneEnvironment type that comes with a collection of commonly used effects
353 built-in. The effects are exposed through a set of properties that are
354 prefixed with the name of the effect they control.
356 When enabling one or more of these effects, the result is similar to
357 manually adding post-processing effects to the SceneEnvironment's
358 \l{SceneEnvironment::effects}{effects} list. ExtendedSceneEnvironment
359 provides however effects that are not available in standalone form, and
360 more importantly, \b{it efficiently combines the effects that are enabled,
361 reducing the number of additional render passes needed, which can lead to
362 significantly better performance than applying individual post-processing
363 effects} to the scene. ExtendedSceneEnvironment also plays well with
364 tonemapping, even for the more complicated multiple pass effects, and also
365 when multiple effects are enabled and combined together. This was not
366 always the case with standalone effects.
368 \note If additional post-processing effects are added to the
369 \l{SceneEnvironment::effects}{effects} list of \l SceneEnvironment, then
370 those effects will be applied \e before the effects provided by the \l
371 ExtendedSceneEnvironment type.
373 Certain features of SceneEnvironment, such as the tonemapping, are
374 inherited and extended with additional properties in
375 ExtendedSceneEnvironment. For example, SceneEnvironment offers the
376 \l{SceneEnvironment::tonemapMode}{tonemapMode} property, whereas
377 ExtendedSceneEnvironment adds control over the exposure, white point,
378 sharpening, and dithering settings of the tonemapper as well. The
379 \l{SceneEnvironment::tonemapMode}{tonemapMode} property is not duplicated
380 however since ExtendedSceneEnvironment inherits everything from
381 SceneEnvironment, so the base setting of the tonemapping mode is usable
382 regardless of which type of environment is associated with a View3D, but
383 the additional properties are available only when using
384 ExtendedSceneEnvironment. Other effects, such as screen space ambient
385 occlusion (SSAO) or fog are fully part of SceneEnvironment and are usable
386 with both types of environments.
388 \section1 Getting Started with ExtendedSceneEnvironment
390 To use the additional features offered by ExtendedSceneEnvironment,
391 associate the View3D with an instance of it. Do not forget to import the
392 \c{QtQuick3D.Helpers} module.
396 import QtQuick3D.Helpers
399 environment: ExtendedSceneEnvironment {
400 tonemapMode: SceneEnvironment.Filmic
401 vignetteEnabled: true
407 \note Experimenting with the effect parameters and tuning the values to
408 achieve the desired visual results can often be more productive when done
409 visually, with controls such as sliders that give instant feedback in the
410 rendered scene when a value is changed. Using a designer tool such as Qt
411 Design Studio, or a test bed similar to the \l{Qt Quick 3D - Scene Effects
412 Example} is therefore often recommendable when aiming to set up a high
413 quality scene that looks visually appealing.
415 \note Switching SceneEnvironment to ExtendedSceneEnvironment automatically
416 implies at least one additional render pass, just as if an Effect with a
417 single pass was added to the
418 \l{SceneEnvironment::effects}{SceneEnvironment's effect list}.
419 This is true regardless of how many of the individual post-processing steps
420 are enabled. (the more complex effects may involve more than one additional
423 \section1 Available Effects
425 Below is an overview of the effects and related features provided by
426 ExtendedSceneEnvironment, including features inherited from
431 \li \l{SceneEnvironment::tonemapMode}{Tonemapping} - Controls how colors
432 are tonemapped from high definition range to the 0-1 range before being
433 displayed. ExtendedSceneEnvironment adds additional controls over the
434 exposure, white point, sharpening, and dithering.
436 Controlled by the properties \l tonemapMode, \l exposure, \l whitePoint, \l
439 \image extendedsceneenvironment_tonemap.jpg
441 \li \l{colorAdjustmentsEnabled}{Color adjustments} - Brightness, contrast,
442 saturation adjustment.
444 Controlled by the properties \l colorAdjustmentsEnabled, \l
445 adjustmentBrightness, \l adjustmentContrast, \l adjustmentSaturation.
447 \image extendedsceneenvironment_coloradj.jpg
449 \li \l{lutEnabled}{Color grading} via lookup table (LUT) textures.
451 Controlled by the properties \l lutEnabled, \l lutSize, \l lutFilterAlpha.
453 \image extendedsceneenvironment_colorgrade.jpg
455 \li \l{depthOfFieldEnabled}{Depth of field}
457 Controlled by the properties \l depthOfFieldEnabled, \l
458 depthOfFieldFocusDistance, \l depthOfFieldFocusRange, \l
459 depthOfFieldBlurAmount.
461 \image extendedsceneenvironment_dof.jpg
463 \li \l{glowEnabled}{Glow and bloom}
465 Controlled by the properties \l glowEnabled, \l glowQualityHigh, \l
466 glowUseBicubicUpscale, \l glowStrength, \l glowIntensity, \l glowBloom, \l
467 glowBlendMode, \l glowHDRMaximumValue, \l glowHDRMinimumValue, \l
470 \image extendedsceneenvironment_glow.jpg
472 \li \l{vignetteEnabled}{Vignette}
474 Controlled by the properties \l vignetteEnabled, \l vignetteStrength, \l
475 vignetteColor, \l vignetteRadius.
477 \image extendedsceneenvironment_vignette.jpg
479 \li \l{lensFlareEnabled}{Lens flare}
481 Controlled by the properties \l lensFlareEnabled, \l lensFlareBloomBias, \l
482 lensFlareGhostDispersal, \l lensFlareGhostCount, \l lensFlareHaloWidth, \l
483 lensFlareStretchToAspect, \l lensFlareDistortion, \l lensFlareBlurAmount,
484 \l lensFlareApplyDirtTexture, \l lensFlareApplyStarburstTexture, \l
485 lensFlareCameraDirection, \l lensFlareLensColorTexture, \l
486 lensFlareLensDirtTexture, \l lensFlareLensStarburstTexture.
488 \image extendedsceneenvironment_lensflare.jpg
490 \li \l{SceneEnvironment::aoStrength}{Screen space ambient occlusion} -
491 Provided by \l SceneEnvironment.
493 Controlled by \l{SceneEnvironment::aoEnabled},
494 \l{SceneEnvironment::aoStrength}, \l{SceneEnvironment::aoDistance},
495 \l{SceneEnvironment::aoSoftness}, \l{SceneEnvironment::aoDither},
496 \l{SceneEnvironment::aoSampleRate}, \l{SceneEnvironment::aoBias}.
498 \image extendedsceneenvironment_ssao.jpg
500 \li \l{SceneEnvironment::fog}{Fog} - Provided by \l SceneEnvironment. This
501 is not a post-processing type of effect, but is rather applied to the
502 materials of the renderable objects in the scene.
504 Controlled by the \l{QtQuick3D::Fog}{Fog} object associated with the
505 \l{SceneEnvironment::fog} property.
507 \image extendedsceneenvironment_fog.jpg
509 \li \l{SceneEnvironment::antialiasingMode}{Antialiasing} - Multisampling,
510 supersampling, progressive antialiasing, specular antialiasing, temporal
511 antialiasing are provided by \l SceneEnvironment. \l
512 ExtendedSceneEnvironment adds the option for using \l{fxaaEnabled}{a form
515 FXAA is controlled by \l fxaaEnabled. Other antialiasing modes are
516 controlled by \l{SceneEnvironment::antialiasingMode},
517 \l{SceneEnvironment::temporalAAEnabled},
518 \l{SceneEnvironment::temporalAAStrength}, and
519 \l{SceneEnvironment::specularAAEnabled}.
521 \image extendedsceneenvironment_aa.jpg
525 \sa SceneEnvironment, {Qt Quick 3D - Scene Effects Example}
528// Depth of Field Effect
529/*! \qmlproperty bool ExtendedSceneEnvironment::depthOfFieldEnabled
530 Enables the depth of field blur effect.
534/*! \qmlproperty real ExtendedSceneEnvironment::depthOfFieldFocusDistance
535 Sets the distance from the camera at which objects are in focus.
540 \l{https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/Sponza}{Sponza}
541 scene has a scale of \c 100 applied in order to have a suitably big range
542 to get blur applied to the back and the front of the view. The picture
543 below is taken with a focus distance of 753 and a focus range of 482.
545 \image extendedsceneenvironment_dof.jpg
547/*! \qmlproperty real ExtendedSceneEnvironment::depthOfFieldFocusRange
548 The distance around the \l
549 {ExtendedSceneEnvironment::depthOfFieldFocusDistance}{depthOfFieldFocusDistance}
550 where items are fully in focus. The focus then fades away to fully blurred
551 by the same distance on both the near and far sides.
555/*! \qmlproperty real ExtendedSceneEnvironment::depthOfFieldBlurAmount Sets the
556 amount of blur applied to objects outside the focus range. Sensible values are
557 in the range \b 0 to \b 10. A value of 0 applies no additional blur.
564 \li Blur amount of 15
566 \li \image extendedsceneenvironment_dof_no_blur.jpg
567 \li \image extendedsceneenvironment_dof_15_blur.jpg
572 \qmlproperty enumeration ExtendedSceneEnvironment::tonemapMode
574 This property defines how colors are tonemapped before rendering. All
575 rendering in Qt Quick 3D is performed in linear color space and can in
576 many cases lead to generating color values that are not displayable. The
577 tonemapMode determines the technique that is used to remap colors into a
580 The default value is \c SceneEnvironment.TonemapModeLinear
582 \value SceneEnvironment.TonemapModeNone
583 All Tonemapping is bypassed. This mode is useful when performing post
585 \value SceneEnvironment.TonemapModeLinear
586 Linear tonemapping is applied. Colors are gamma corrected and returned
588 \value SceneEnvironment.TonemapModeAces
589 Academy Color Encoding System tonemapping is applied.
590 \value SceneEnvironment.TonemapModeHejlDawson
591 Hejl-Dawson tonemapping is applied.
592 \value SceneEnvironment.TonemapModeFilmic
593 Filmic tonemapping is applied.
595 \note When using post-processing effects, many effects expect untonemapped
596 linear color data. It is important to bypass the built-in tonemapping in
597 this case by using the \c SceneEnvironment.TonemapModeNone value. This does
598 not apply to the built-in effects of ExtendedSceneEnvironment because those
599 automatically take care of proper tonemapping.
607 \li \image extendedsceneenvironment_tonemap_none.jpg
610 \li \image extendedsceneenvironment_tonemap_linear.jpg
613 \li \image extendedsceneenvironment_tonemap_aces.jpg
616 \li \image extendedsceneenvironment_tonemap_hejldawson.jpg
619 \li \image extendedsceneenvironment_tonemap_filmic.jpg
622/*! \qmlproperty real ExtendedSceneEnvironment::exposure
623 Exposure level used by the tonemapper.
629 \li Filmic tonmapping with exposure 8
630 \li Filmic tonmapping with exposure set to 0.5
632 \li \image extendedsceneenvironment_tonemap_exposure_8.jpg
633 \li \image extendedsceneenvironment_tonemap_exposure_05.jpg
636/*! \qmlproperty real ExtendedSceneEnvironment::whitePoint
638 Reference value for \e white when tonemapping is enabled. The value must be
641 \note This value is ignored when using \l{SceneEnvironment::tonemapMode}{SceneEnvironment.TonemapModeLinear}.
647 \li Filmic tonmapping with white point set to 0.1
648 \li Filmic tonmapping with white point set to 1
650 \li \image extendedsceneenvironment_tonemap_whitepoint_01.jpg
651 \li \image extendedsceneenvironment_tonemap_whitepoint_1.jpg
654/*! \qmlproperty bool ExtendedSceneEnvironment::ditheringEnabled
655 Enables dithering to reduce banding artifacts.
659/*! \qmlproperty real ExtendedSceneEnvironment::sharpnessAmount
660 Set the sharpening amount. Valid values are from \c 0.0 (off) to \c 1.0 (full).
666 \li Filmic tonmapping with sharpness set to 0
667 \li Filmic tonmapping with sharpness set to 1
669 \li \image extendedsceneenvironment_tonemap_sharpness_0.jpg
670 \li \image extendedsceneenvironment_tonemap_sharpness_1.jpg
674/*! \qmlproperty bool ExtendedSceneEnvironment::fxaaEnabled
675 Enables fast approximate anti-aliasing (FXAA).
682 \li \image extendedsceneenvironment_without_fxaa.jpg
683 \li \image extendedsceneenvironment_with_fxaa.jpg
689/*! \qmlproperty bool ExtendedSceneEnvironment::colorAdjustmentsEnabled
691 Enables color adjustments.
694 \sa {ExtendedSceneEnvironment::colorAdjustmentsEnabled}{colorAdjustmentsEnabled}
696/*! \qmlproperty real ExtendedSceneEnvironment::adjustmentBrightness
697 Adjusts the brightness of the scene.
704 \li \image extendedsceneenvironment_brightness_contrast_saturation_at_1.jpg
705 \li \image extendedsceneenvironment_brightness_at_4.jpg
710/*! \qmlproperty real ExtendedSceneEnvironment::adjustmentContrast
711 Adjusts the contrast of the scene.
718 \li \image extendedsceneenvironment_brightness_contrast_saturation_at_1.jpg
719 \li \image extendedsceneenvironment_contrast_at_4.jpg
724/*! \qmlproperty real ExtendedSceneEnvironment::adjustmentSaturation
725 Adjusts the saturation of the scene.
732 \li \image extendedsceneenvironment_brightness_contrast_saturation_at_1.jpg
733 \li \image extendedsceneenvironment_saturation_at_4.jpg
738// Color Grading Effect
739/*! \qmlproperty bool ExtendedSceneEnvironment::lutEnabled
740 Enables color grading with look-up tables (LUTs).
741 The look-up table is given as a texture.
745/*! \qmlproperty real ExtendedSceneEnvironment::lutSize
746 Sets the size of the LUT texture. The texture should have the dimensions:
748 \c {width = lutSize * lutSize}
750 \c {height = lutSize}
754/*! \qmlproperty real ExtendedSceneEnvironment::lutFilterAlpha
755 Sets the amount of color grading to mix with the scene.
756 The value is expected to be between \b 0 and \b 1.
760/*! \qmlproperty Texture ExtendedSceneEnvironment::lutTexture
761 Source of look-up texture. If no texture is set a built-in identity
764 Pictured below is an example texture with a size of 256x16, matching the
765 default \l lutSize of 16.
767 \image extendedsceneenvironment_lut_texture_used_for_invert.jpg
769 The result of this effect:
771 \image extendedsceneenvironment_lut_invert.jpg
774/*! \qmlproperty bool ExtendedSceneEnvironment::glowEnabled
775 Enables the glow effect. It can also provide bloom, when the value of \l
776 glowBloom is larger than 0.
780/*! \qmlproperty bool ExtendedSceneEnvironment::glowQualityHigh
781 Increases the samples used for the glow when downsampling to improve the
782 quality of the glow effect.
786 \note Enabling this is a trade off between rendering quality and performance. Consider if
787 \l {ExtendedSceneEnvironment::ditheringEnabled}{dithering} can be used instead.
789/*! \qmlproperty bool ExtendedSceneEnvironment::glowUseBicubicUpscale
790 Reduces the aliasing artifacts and boxing in the glow effect.
794 \note Using bi-cubic up-scaling will come at the cost of performance. Consider if
795 \l {ExtendedSceneEnvironment::ditheringEnabled}{dithering} can be used instead.
797/*! \qmlproperty real ExtendedSceneEnvironment::glowStrength
798 Glow strength. Acceptable values are from \b 0 to \b 2.
800 The strength is effectively a scale factor (multiplier) that is applied
801 per-level. This means the the more levels are enabled in \l glowLevel, the
802 more pronounced effect a larger glowStrength has.
804 In practice the values for \l glowStrength, \l glowIntensity, and \l
805 glowBloom will often be tuned together to achieve the desired results.
809 For example, with a glowIntensity of 1.0, glowBloom of 0.25, and the
810 first four levels enabled:
814 \li glowStrength of 0.5
815 \li glowStrength of 1.5
817 \li \image extendedsceneenvironment_glow_strength_05.jpg
818 \li \image extendedsceneenvironment_glow_strength_15.jpg
822/*! \qmlproperty real ExtendedSceneEnvironment::glowIntensity
823 Glow intensity. Expected values are in the range \b 0 to \b 8.
825 The intensity is effectively a scale factor (multiplier) for the
826 accumulated glow color (including all levels).
828 In practice the values for \l glowStrength, \l glowIntensity, and \l
829 glowBloom will often be tuned together to achieve the desired results.
833 For example, with a glowStrength of 1.0 and glowBloom of 0.25:
837 \li glowIntensity of 0.25
838 \li glowIntensity of 1.25
840 \li \image extendedsceneenvironment_glow_intensity_025.jpg
841 \li \image extendedsceneenvironment_glow_intensity_125.jpg
844/*! \qmlproperty real ExtendedSceneEnvironment::glowBloom
845 Sets the amount of bloom applied to the glow effect.
846 Values from \b 0 to \b 1 are expected.
848 The \l glowHDRMinimumValue, \l glowHDRMaximumValue, \l glowHDRScale, and \l
849 glowBloom values together control the amount of \c{luminance feedback}
850 generated by the glow/bloom effect.
854 In practice the values for \l glowStrength, \l glowIntensity, and \l
855 glowBloom will often be tuned together to achieve the desired results.
857 For example, with four glow levels enabled, a strength of 1.5, and an
862 \li glowBloom set to 0
863 \li glowBloom set to 0.5
865 \li \image extendedsceneenvironment_glow_level4_strength15_intensity1_bloom0.jpg
866 \li \image extendedsceneenvironment_glow_level4_strength15_intensity1_bloom05.jpg
869/*! \qmlproperty int ExtendedSceneEnvironment::glowBlendMode
870 Blending mode for the glow effect.
874 \li ExtendedSceneEnvironment.GlowBlendMode.Additive
875 \li ExtendedSceneEnvironment.GlowBlendMode.Screen
876 \li ExtendedSceneEnvironment.GlowBlendMode.SoftLight
877 \li ExtendedSceneEnvironment.GlowBlendMode.Replace
880 \default ExtendedSceneEnvironment.GlowBlendMode.SoftLight
882 \c Additive is often recommendable for outdoor scenes, where a sky or sun
883 is visible, whereas the default \c SoftLight may work better for in-door
886 \c Replace does not perform any blending, but rather results in displaying
887 only the contribution the glow/bloom effect would blend with the actual
888 content. In practice this can be useful for experimenting and
889 troubleshooting when setting up the parameters of a glow/bloom effect.
897 \li \image extendedsceneenvironment_glow_disabled.jpg
900 \li \image extendedsceneenvironment_glow_additive.jpg
903 \li \image extendedsceneenvironment_glow_screen.jpg
906 \li \image extendedsceneenvironment_glow_softlight.jpg
909 \li \image extendedsceneenvironment_glow_replace.jpg
912/*! \qmlproperty real ExtendedSceneEnvironment::glowHDRMaximumValue
913 Sets the maximum brightness of the glow, in high dynamic range.
914 Value range is from \b 0 to \b 256.
916 The \l glowHDRMinimumValue, \l glowHDRMaximumValue, \l glowHDRScale, and \l
917 glowBloom values together control the amount of \c{luminance feedback}
918 generated by the glow/bloom effect.
922/*! \qmlproperty real ExtendedSceneEnvironment::glowHDRMinimumValue
923 Sets the minimum brightness of the glow, in high dynamic range.
924 Expected values are in the range \b 0 to \b 4.
926 The \l glowHDRMinimumValue, \l glowHDRMaximumValue, \l glowHDRScale, and \l
927 glowBloom values together control the amount of \c{luminance feedback}
928 generated by the glow/bloom effect.
932/*! \qmlproperty real ExtendedSceneEnvironment::glowHDRScale
933 The bleed scale of the HDR glow.
934 Expected values are in the range \b 0 to \b 8.
936 The \l glowHDRMinimumValue, \l glowHDRMaximumValue, \l glowHDRScale, and \l
937 glowBloom values together control the amount of \c{luminance feedback}
938 generated by the glow/bloom effect.
942/*! \qmlproperty int ExtendedSceneEnvironment::glowLevel
943 Sets which of the blur passes get applied to the glow effect. There are a
944 total of 7 levels available.
946 Not having any levels set means that the glow will have no visual effect.
948 For example, to enable Glow Level \e One and \e Six we just OR the two enums together:
950 glowLevel = (ExtendedSceneEnvironment.GlowLevel.One | ExtendedSceneEnvironment.GlowLevel.Six)
961 \li \image extendedsceneenvironment_glow_levels_1.jpg
964 \li \image extendedsceneenvironment_glow_levels_1_2.jpg
966 \li One | Two | Three
967 \li \image extendedsceneenvironment_glow_levels_1_2_3.jpg
969 \li One | Two | Three | Four
970 \li \image extendedsceneenvironment_glow_levels_1_2_3_4.jpg
976/*! \qmlproperty bool ExtendedSceneEnvironment::vignetteEnabled
977 Enables the vignette effect.
981/*! \qmlproperty real ExtendedSceneEnvironment::vignetteStrength
982 Sets the strength of the vignette effect. Ranges from \b 0 to \b 15.
991 \li \image extendedsceneenvironment_vignette_strength_15.jpg
992 \li \image extendedsceneenvironment_vignette_strength_10.jpg
995/*! \qmlproperty color ExtendedSceneEnvironment::vignetteColor
996 Sets the color of the vignette effect.
1000 For example, changing the color to red, pictured here with radius 4 and
1003 \image extendedsceneenvironment_vignette_red.jpg
1005/*! \qmlproperty real ExtendedSceneEnvironment::vignetteRadius
1006 Sets the radius of the vignette effect. Ranges from \b 0 to \b 5.
1015 \li \image extendedsceneenvironment_vignette_radius_default.jpg
1016 \li \image extendedsceneenvironment_vignette_radius_5.jpg
1020/*! \qmlproperty bool ExtendedSceneEnvironment::lensFlareEnabled
1021 Enables the lens flare effect.
1023 Once enabled, the first property to tune is typically \l
1028/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareBloomScale
1029 Sets the scale of the lens flare bloom effect. Expected scale value ranges
1032 In practice this acts as a multiplier for the zero-clamped color value with
1033 the \l lensFlareBloomBias subtracted.
1039 \li Scale 2, bias 0.81
1040 \li Scale 20, bias 0.81
1042 \li \image extendedsceneenvironment_lensflare_scale_2_bias_081.jpg
1043 \li \image extendedsceneenvironment_lensflare_scale_20_bias_081.jpg
1046/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareBloomBias
1047 Sets the level at which the lens flare bloom starts.
1049 The bias value is subtracted from the high dynamic range color value, with
1050 the result clamped to 0. This means that, depending on the scene, it may
1051 sometimes need be set to a quite low value, e.g. below 1, in order to make
1052 the lens flare obvious. Hence the default of 0.95. Whereas when having a
1053 higher range of colors, a bigger value may make more sense.
1062 \li \image extendedsceneenvironment_lensflare_bias_081.jpg
1063 \li \image extendedsceneenvironment_lensflare_bias_031.jpg
1066/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareGhostDispersal
1067 Sets the distance between the lens flare ghosts. Expected values are
1068 between \b 0 and \b 5. The value should be larger than 0.
1074 \li Ghost dispersal of 0.25
1075 \li Ghost dispersal of 0.90
1077 \li \image extendedsceneenvironment_lensflare_ghostdispersal_025.jpg
1078 \li \image extendedsceneenvironment_lensflare_ghostdispersal_090.jpg
1081/*! \qmlproperty int ExtendedSceneEnvironment::lensFlareGhostCount
1082 Sets the amount of lens flare ghosts. Expected values are from \b 0 to \b 20.
1088 \li Ghost count of 2
1089 \li Ghost count of 16
1091 \li \image extendedsceneenvironment_lensflare_ghostcount_2.jpg
1092 \li \image extendedsceneenvironment_lensflare_ghostcount_16.jpg
1095/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareHaloWidth
1096 Sets the size of the lens flare halo. Ranges from \b 0 to \b 1.
1100/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareStretchToAspect
1101 Set correction factor for roundness of the lens flare halo.
1105/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareDistortion
1106 Set amount of chromatic aberration in the lens flare. Expected values
1107 ranges from \b 0 to \b 20.
1113 \li Distortion set to 0
1114 \li Distortion set to 15
1116 \li \image extendedsceneenvironment_lensflare_distortion_0.jpg
1117 \li \image extendedsceneenvironment_lensflare_distortion_15.jpg
1120/*! \qmlproperty real ExtendedSceneEnvironment::lensFlareBlurAmount
1121 Set amount of blur to apply to the lens flare. Ranges from \b 0 to \b 50.
1127 \li Blur amount set to 0
1128 \li Blur amount set to 30
1130 \li \image extendedsceneenvironment_lensflare_0_blur.jpg
1131 \li \image extendedsceneenvironment_lensflare_30_blur.jpg
1135/*! \qmlproperty bool ExtendedSceneEnvironment::lensFlareApplyDirtTexture
1136 Set whether to apply a dirt texture to the lens flare.
1142 \li Dirt texture disabled
1143 \li Default dirty texture enabled
1145 \li \image extendedsceneenvironment_lensflare_dirt_off.jpg
1146 \li \image extendedsceneenvironment_lensflare_dirt_on.jpg
1149 \sa {ExtendedSceneEnvironment::lensFlareLensDirtTexture}{lensFlareLensDirtTexture}
1151/*! \qmlproperty bool ExtendedSceneEnvironment::lensFlareApplyStarburstTexture
1152 Set whether to apply a starburst texture to the lens flare.
1158 \li Starburst texture disabled
1159 \li Default starburst texture enabled
1161 \li \image extendedsceneenvironment_lensflare_starburst_off.jpg
1162 \li \image extendedsceneenvironment_lensflare_starburst_on.jpg
1165 \sa {ExtendedSceneEnvironment::lensFlareLensStarburstTexture}{lensFlareLensStarburstTexture}
1167/*! \qmlproperty vector3d ExtendedSceneEnvironment::lensFlareCameraDirection
1168 Sets the direction of the camera in the scene.
1170 \default Qt.vector3d(0, 0, -1)
1172/*! \qmlproperty Texture ExtendedSceneEnvironment::lensFlareLensColorTexture
1173 A gradient image used for the lens flare lens color.
1175 By default a built-in 256x256 texture is used:
1177 \image extendedsceneenvironment_lensflare_default_texture.jpg
1179/*! \qmlproperty Texture ExtendedSceneEnvironment::lensFlareLensDirtTexture
1180 An image that is used to simulate inperfections on the lens.
1182 Has an effect only when \l lensFlareApplyDirtTexture is enabled.
1184 By default a built-in dirty texture is used:
1186 \image extendedsceneenvironment_lensflare_default_dirt.jpg
1188/*! \qmlproperty Texture ExtendedSceneEnvironment::lensFlareLensStarburstTexture
1189 A noise image to augment the starburst effect of the lens flare.
1190 Has an effect only when \l lensFlareApplyStarburstTexture is enabled.
1192 By default a built-in noise texture is used:
1194 \image extendedsceneenvironment_lensflare_default_noise.jpg