From 8449e5a1ffa7f3677c79aa2e4afa5dfd1bf4a652 Mon Sep 17 00:00:00 2001 From: Max Hilbrunner Date: Sun, 15 Oct 2023 01:44:49 +0200 Subject: [PATCH] Merge pull request #8233 from Calinou/visibility-ranges-visibility-parent Document Visibility Parent functionality in Visibility Ranges --- tutorials/3d/visibility_ranges.rst | 82 +++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 6 deletions(-) diff --git a/tutorials/3d/visibility_ranges.rst b/tutorials/3d/visibility_ranges.rst index a73f49f8b..28cfdff20 100644 --- a/tutorials/3d/visibility_ranges.rst +++ b/tutorials/3d/visibility_ranges.rst @@ -94,6 +94,8 @@ the following properties in the GeometryInstance3D's **Visibility Range** sectio - **Fade Mode:** Controls how the transition between LOD levels should be performed. See below for details. +.. _doc_visibility_ranges_fade_mode: + Fade mode ^^^^^^^^^ @@ -112,14 +114,82 @@ choose from: hystereis distance is determined by **Visibility Range > Begin Margin** and **Visibility Range > End Margin**. This mode provides the best performance as it doesn't force rendering to become transparent during the fade transition. -- **Self:** Uses alpha blending to smoothly fade between LOD levels. The fade - transition distance is determined by **Visibility Range > Begin Margin** and - **Visibility Range > End Margin**. This mode forces transparent rendering on - the object during its fade transition, so it has a performance impact. -- **Dependencies:** This is intended for hierarchical LOD systems, and acts the - same as **Self** if visibility ranges are used to perform non-hierarchical +- **Self:** Uses alpha blending to smoothly fade between LOD levels. The node + will fade-out itself when reaching the limits of its own visibility range. The + fade transition distance is determined by **Visibility Range > Begin Margin** + and **Visibility Range > End Margin**. This mode forces transparent rendering + on the object during its fade transition, so it has a performance impact. +- **Dependencies:** Uses alpha blending to smoothly fade between LOD levels. The + node will fade-in its dependencies when reaching the limits of its own + visibility range. The fade transition distance is determined by **Visibility + Range > Begin Margin** and **Visibility Range > End Margin**. This mode forces + transparent rendering on the object during its fade transition, so it has a + performance impact. This mode is intended for hierarchical LOD systems using + :ref:`Visibility parent `. It acts + the same as **Self** if visibility ranges are used to perform non-hierarchical LOD. +.. _doc_visibility_ranges_visibility_parent: + +Visibility parent +^^^^^^^^^^^^^^^^^ + +The **Visibility Parent** property makes it easier to set up +:abbr:`HLOD (Hierarchical Level of Detail)`. It allows automatically hiding +child nodes if its parent is visible given its current visibility range properties. + +.. note:: + + The target of **Visibility Parent** *must* inherit from + :ref:`class_GeometryInstance3D`. + + Despite its name, the **Visibility Parent** property *can* point to a node + that is not a parent of the node in the scene tree. However, it is + impossible to point **Visibility Parent** towards a child node, as this + creates a dependency cycle which is not supported. You will get an error + message in the Output panel if a dependency cycle occurs. + +Given the following scene tree (where all nodes inherit from GeometryInstance3D): + +:: + + ┖╴BatchOfHouses + ┠╴House1 + ┠╴House2 + ┠╴House3 + ┖╴House4 + +In this example, *BatchOfHouses* is a large mesh designed to represent all child +nodes when viewed at a distance. *House1* to *House4* are smaller +MeshInstance3Ds representing individual houses. To configure HLOD in this +example, we only need to configure two things: + +- Set **Visibility Range Begin** to a number greater than `0.0` so that + *BatchOfHouses* only appears when far away enough from the camera. Below this + distance, we want *House1* to *House4* to be displayed instead. +- On *House1* to *House4*, assign the **Visibility Parent** property to *BatchOfHouses*. + +This makes it easier to perform further adjustments, as you don't need to adjust +the **Visibility Range Begin** of *BatchOfHouses* and **Visibility Range End** +of *House1* to *House4*. + +Fade mode is automatically handled by the **Visibility Parent** property, so +that the child nodes only become hidden once the parent node is fully faded out. +This is done to minimize visible pop-in. Depending on your :abbr:`HLOD +(Hierarchical Level of Detail)` setup, you may want to try both the **Self** and +**Dependencies** :ref:`fade modes `. + +.. note:: + + Nodes hidden via the **Visible** property are essentially removed from the + visibility dependency tree, so dependent instances will not take the hidden + node or its ancestors into account. + + In practice, this means that if the target of the **Visibility Parent** node + is hidden by setting its **Visible** property to ``false``, the node will + not be hidden according to the **Visibility Range Begin** value specified in + the visibility parent. + Configuration tips ------------------