diff --git a/doc/qtdesignstudio/config/style/qt5-sidebar.html b/doc/qtdesignstudio/config/style/qt5-sidebar.html index 22b2895dc89..994ecd3db30 100644 --- a/doc/qtdesignstudio/config/style/qt5-sidebar.html +++ b/doc/qtdesignstudio/config/style/qt5-sidebar.html @@ -16,6 +16,7 @@
  • Creating Projects
  • Use Cases
  • Concepts and Terms
    • +
  • Best Practices
  • Examples
    • diff --git a/doc/qtdesignstudio/images/bleed-scale-1.webp b/doc/qtdesignstudio/images/bleed-scale-1.webp new file mode 100644 index 00000000000..cfe9d7bd7e0 Binary files /dev/null and b/doc/qtdesignstudio/images/bleed-scale-1.webp differ diff --git a/doc/qtdesignstudio/images/bleed-scale-8.webp b/doc/qtdesignstudio/images/bleed-scale-8.webp new file mode 100644 index 00000000000..3d4ef0b7834 Binary files /dev/null and b/doc/qtdesignstudio/images/bleed-scale-8.webp differ diff --git a/doc/qtdesignstudio/images/bleed-scale-no.webp b/doc/qtdesignstudio/images/bleed-scale-no.webp new file mode 100644 index 00000000000..e102ae7501a Binary files /dev/null and b/doc/qtdesignstudio/images/bleed-scale-no.webp differ diff --git a/doc/qtdesignstudio/images/ext-scene-env-navigator.webp b/doc/qtdesignstudio/images/ext-scene-env-navigator.webp new file mode 100644 index 00000000000..675a9aedfcc Binary files /dev/null and b/doc/qtdesignstudio/images/ext-scene-env-navigator.webp differ diff --git a/doc/qtdesignstudio/images/glow-additive-blend.webp b/doc/qtdesignstudio/images/glow-additive-blend.webp new file mode 100644 index 00000000000..418628fc8be Binary files /dev/null and b/doc/qtdesignstudio/images/glow-additive-blend.webp differ diff --git a/doc/qtdesignstudio/images/glow-bicubic.webp b/doc/qtdesignstudio/images/glow-bicubic.webp new file mode 100644 index 00000000000..216a2487088 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-bicubic.webp differ diff --git a/doc/qtdesignstudio/images/glow-example-project.webp b/doc/qtdesignstudio/images/glow-example-project.webp new file mode 100644 index 00000000000..2163fee2d91 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-example-project.webp differ diff --git a/doc/qtdesignstudio/images/glow-example.webp b/doc/qtdesignstudio/images/glow-example.webp new file mode 100644 index 00000000000..4de776aa443 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-example.webp differ diff --git a/doc/qtdesignstudio/images/glow-high-quality.webp b/doc/qtdesignstudio/images/glow-high-quality.webp new file mode 100644 index 00000000000..80434dde67a Binary files /dev/null and b/doc/qtdesignstudio/images/glow-high-quality.webp differ diff --git a/doc/qtdesignstudio/images/glow-no-enhancment.webp b/doc/qtdesignstudio/images/glow-no-enhancment.webp new file mode 100644 index 00000000000..87d90da35f1 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-no-enhancment.webp differ diff --git a/doc/qtdesignstudio/images/glow-properties.webp b/doc/qtdesignstudio/images/glow-properties.webp new file mode 100644 index 00000000000..b2d22736eb3 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-properties.webp differ diff --git a/doc/qtdesignstudio/images/glow-replace-blend.webp b/doc/qtdesignstudio/images/glow-replace-blend.webp new file mode 100644 index 00000000000..06c8e8c6692 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-replace-blend.webp differ diff --git a/doc/qtdesignstudio/images/glow-screen-blend.webp b/doc/qtdesignstudio/images/glow-screen-blend.webp new file mode 100644 index 00000000000..6a18367cb92 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-screen-blend.webp differ diff --git a/doc/qtdesignstudio/images/glow-softlight-blend.webp b/doc/qtdesignstudio/images/glow-softlight-blend.webp new file mode 100644 index 00000000000..3ac9ef26406 Binary files /dev/null and b/doc/qtdesignstudio/images/glow-softlight-blend.webp differ diff --git a/doc/qtdesignstudio/images/glow_all_blur_levels.webp b/doc/qtdesignstudio/images/glow_all_blur_levels.webp new file mode 100644 index 00000000000..a5cc30d9cc0 Binary files /dev/null and b/doc/qtdesignstudio/images/glow_all_blur_levels.webp differ diff --git a/doc/qtdesignstudio/images/glow_high_blur_levels.webp b/doc/qtdesignstudio/images/glow_high_blur_levels.webp new file mode 100644 index 00000000000..7cdf15a5c5c Binary files /dev/null and b/doc/qtdesignstudio/images/glow_high_blur_levels.webp differ diff --git a/doc/qtdesignstudio/images/glow_low_blur_levels.webp b/doc/qtdesignstudio/images/glow_low_blur_levels.webp new file mode 100644 index 00000000000..a59ed6cd7e8 Binary files /dev/null and b/doc/qtdesignstudio/images/glow_low_blur_levels.webp differ diff --git a/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc b/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc new file mode 100644 index 00000000000..22a71ec681d --- /dev/null +++ b/doc/qtdesignstudio/src/best practices/best-practices-glow.qdoc @@ -0,0 +1,200 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage best-practices.html + \page best-practices-glow.html + \nextpage {Examples} + + \title Creating Glow and Bloom Effects + + In \QDS, you can add a glow and bloom effect to your 3D scene using the + \uicontrol ExtendedSceneEnvironment component (available in Qt 6.5 and later). With this effect, + you can, for example, create glow around illuminated areas (such as material or skyboxes when + using image-based lighting) or add ambient light. Using the glow effect is one way to make your + scene more realistic. + + \image glow-example.webp + + \section1 Creating a Project with ExtendedSceneEnvironment + + To create a project with \uicontrol ExtendedSceneEnvironment as the default + scene environment, use the \uicontrol {3D Extended} project preset. + + For more information about creating projects, see \l{Creating Projects}. + + \section1 Adding ExtendedSceneEnvironment to an Existing Project + + To add \uicontrol {ExtendedSceneEnvironment} to an existing project, drag the + \uicontrol {ExtendedSceneEnvironment} component from \uicontrol Components to + the \uicontrol 2D or \uicontrol Navigator view. + + \image ext-scene-env-navigator.webp + + \section1 Enabling the Glow Effect + + To enable the glow effect, select \e SceneEnvironment in the \uicontrol Navigator view and + then, in the \uicontrol Properties view, select \uicontrol Enabled in the + \uicontrol Glow section. + + \image glow-properties.webp + + \note When setting up or experimenting with the glow effect, use the \l {Blend Modes}{Replace} + blend mode to see the effect more clearly. + + \section1 The Flashlight Example Project + + The flashlight example used in this documentation is available from the \uicontrol Examples + section of the \QDS \uicontrol Welcome page. + + You can use the project to experiment with the \uicontrol Glow properties. When you run the + project, you can control most properties with UI controls. Another way to experiment with + properties is to change them directly in the \uicontrol Properties view in \QDS and see the + changes live in the \uicontrol 2D view. + + \image glow-example-project.webp + + \section1 Basic Properties + + Usually, the best way to achieve a realistic glow effect in your 3D scene is to adjust + the \uicontrol {Strength}, \uicontrol {Intensity}, and \uicontrol {Bloom} + properties together. + + \section2 Strength + + Sets the strength of the glow. If this property has a 0 value, the glow effect is disabled. The + strength is a scale factor (multiplier) applied per level. This means that + with more levels enabled in \l {Blur Levels}, a larger \uicontrol {strength} value has + a more pronounced effect. + + \section2 Intensity + + Sets the intensity of the glow. The intensity is effectively a scale factor (multiplier) for the + accumulated glow color (including all levels). + + \section2 Bloom + + Sets the overall illumination of the whole scene. + + \section2 Lower Threshold + + Sets the minimum level of brightness for the glow. + + \section2 Upper Threshold + + Sets the maximum level of brightness for the glow. + + \section2 HDR Scale + + Sets how much the glow bleeds (or extends) beyond the borders of bright areas + in the scene. The range for this property is 0-8. As seen in the example images below, a high + value gives a very modest bleed, while a low number results in a much more visible bleed. + + \table + \header + \li HDR Scale + \li Example + \row + \li Bloom disabled + \li \image bleed-scale-no.webp + \row + \li 8 + \li \image bleed-scale-8.webp + \row + \li 1 + \li \image bleed-scale-1.webp + \endtable + + \section1 Blur Levels + + Sets which of the blur passes to apply to the glow effect. + + The higher the level is, the more the glow effect spreads around the light source, + and the softer the glow is. + + As seen in the example image below, lower blur levels produce an intense glow within a limited + area, while higher blur levels produce a softer glow in a more extensive area. Combine blur + levels to get the desired result. + + \table + \header + \li Blur level + \li Example + \row + \li 1, 2, 3 + \li \image glow_low_blur_levels.webp + \row + \li 5, 6, 7 + \li \image glow_high_blur_levels.webp + \row + \li 1, 2, 3, 4, 5, 6, 7 + \li \image glow_all_blur_levels.webp + \endtable + + \section2 Blend Modes + + The following blend modes are available: + + \table + \header + \li Blend mode + \li Description + \li Example + \row + \li Additive + \li Often recommended for outdoor scenes with a visible sky or sun. + \li \image glow-additive-blend.webp + \row + \li Screen + \li Similar to \uicontrol {Additive}, but the result is less bright. + \li \image glow-screen-blend.webp + \row + \li SoftLight + \li Often recommended for in-door environments. + \li \image glow-softlight-blend.webp + \row + \li Replace + \li Does not perform any blending, but displays only the contribution + the glow effect would blend with the actual content. In practice, this is useful for + experimenting and troubleshooting when setting up the glow effect. + \li \image glow-replace-blend.webp + \endtable + + \section1 Improvement Properties + + The \uicontrol{High Quality} and \uicontrol{Bicubical Upsampling} + properties improve the quality of the glow blur by upsampling. Using these properties + may slow down the performance of the application. You can also try using the + \uicontrol Dithering property in the \uicontrol sceneEnvironment instead. In some cases, + \uicontrol Dithering renders a similar result but at a lower cost. + + \section2 High Quality + + Increases the samples used for the glow when downsampling to improve the quality of the glow + effect. + + \section2 Bicubical Upsampling + + Reduces the aliasing artifacts and boxing in the glow effect. + + \section2 Examples + + These examples show a zoomed-in image of each effect: + + \table + \header + \li Effect + \li Example + \row + \li No effect + \li \image glow-no-enhancment.webp + \row + \li High Quality + \li \image glow-high-quality.webp + \row + \li Bicubic Upsampling + \li \image glow-bicubic.webp + \endtable + + +*/ diff --git a/doc/qtdesignstudio/src/best-practices.qdoc b/doc/qtdesignstudio/src/best-practices.qdoc new file mode 100644 index 00000000000..91df948f560 --- /dev/null +++ b/doc/qtdesignstudio/src/best-practices.qdoc @@ -0,0 +1,16 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage studio-terms.html + \page best-practices.html + \nextpage best-practices-glow.html + + \title Best Practices + + \section1 Graphics + + \list + \li \l {Creating Glow and Bloom Effects} + \endlist +*/ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc index 0b3e8c68ad9..00464f7447a 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-terms.qdoc @@ -4,7 +4,7 @@ /*! \page studio-terms.html \previouspage studio-use-cases.html - \nextpage {Examples} + \nextpage best-practices.html \title Concepts and Terms diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index b65c116d87c..2da0da559b5 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -48,6 +48,7 @@ \li \l{Creating Projects} \li \l{Use Cases} \li \l{Concepts and Terms} + \li \l{Best Practices} \li \l{Examples} \endlist \li \l{Wireframing} diff --git a/doc/qtdesignstudio/src/qtdesignstudio.qdoc b/doc/qtdesignstudio/src/qtdesignstudio.qdoc index 6aab55a1ad5..d3a0b007d12 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio.qdoc @@ -31,6 +31,7 @@ \li \l{Creating Projects} \li \l{Use Cases} \li \l{Concepts and Terms} + \li \l{Best Practices} \li \l{Examples} \endlist \li \b {\l{Wireframing}}