Improve VisibleOnScreen classes docs
This commit is contained in:
MewPurPur
parent
b467afe65d
commit
53d0ba2913
4 changed files with 29 additions and 23 deletions
|
|
@ -1,19 +1,21 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<class name="VisibleOnScreenEnabler2D" inherits="VisibleOnScreenNotifier2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
||||
<brief_description>
|
||||
Automatically disables another node if not visible on screen.
|
||||
A rectangular region of 2D space that, when visible on screen, enables a target node.
|
||||
</brief_description>
|
||||
<description>
|
||||
VisibleOnScreenEnabler2D detects when it is visible on screen (just like [VisibleOnScreenNotifier2D]) and automatically enables or disables the target node. The target node is disabled when [VisibleOnScreenEnabler2D] is not visible on screen (including when [member CanvasItem.visible] is [code]false[/code]), and enabled when the enabler is visible. The disabling is achieved by changing [member Node.process_mode].
|
||||
[VisibleOnScreenEnabler2D] contains a rectangular region of 2D space and a target node. The target node will be automatically enabled (via its [member Node.process_mode] property) when any part of this region becomes visible on the screen, and automatically disabled otherwise. This can for example be used to activate enemies only when the player approaches them.
|
||||
See [VisibleOnScreenNotifier2D] if you only want to be notified when the region is visible on screen.
|
||||
[b]Note:[/b] [VisibleOnScreenEnabler2D] uses the render culling code to determine whether it's visible on screen, so it won't function unless [member CanvasItem.visible] is set to [code]true[/code].
|
||||
</description>
|
||||
<tutorials>
|
||||
</tutorials>
|
||||
<members>
|
||||
<member name="enable_mode" type="int" setter="set_enable_mode" getter="get_enable_mode" enum="VisibleOnScreenEnabler2D.EnableMode" default="0">
|
||||
Determines how the node is enabled. Corresponds to [enum Node.ProcessMode]. Disabled node uses [constant Node.PROCESS_MODE_DISABLED].
|
||||
Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED].
|
||||
</member>
|
||||
<member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")">
|
||||
The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is invalid, nothing will happen.
|
||||
The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside the scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected.
|
||||
</member>
|
||||
</members>
|
||||
<constants>
|
||||
|
|
|
|||
|
|
@ -1,28 +1,32 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<class name="VisibleOnScreenEnabler3D" inherits="VisibleOnScreenNotifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
||||
<brief_description>
|
||||
Enables certain nodes only when approximately visible.
|
||||
A box-shaped region of 3D space that, when visible on screen, enables a target node.
|
||||
</brief_description>
|
||||
<description>
|
||||
The VisibleOnScreenEnabler3D will disable [RigidBody3D] and [AnimationPlayer] nodes when they are not visible. It will only affect other nodes within the same scene as the VisibleOnScreenEnabler3D itself.
|
||||
If you just want to receive notifications, use [VisibleOnScreenNotifier3D] instead.
|
||||
[b]Note:[/b] VisibleOnScreenEnabler3D uses an approximate heuristic for performance reasons. It doesn't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an [Area3D] node as a child of a [Camera3D] node and/or [method Vector3.dot].
|
||||
[b]Note:[/b] VisibleOnScreenEnabler3D will not affect nodes added after scene initialization.
|
||||
[VisibleOnScreenEnabler3D] contains a box-shaped region of 3D space and a target node. The target node will be automatically enabled (via its [member Node.process_mode] property) when any part of this region becomes visible on the screen, and automatically disabled otherwise. This can for example be used to activate enemies only when the player approaches them.
|
||||
See [VisibleOnScreenNotifier3D] if you only want to be notified when the region is visible on screen.
|
||||
[b]Note:[/b] [VisibleOnScreenEnabler3D] uses an approximate heuristic that doesn't take walls and other occlusion into account, unless occlusion culling is used. It also won't function unless [member Node3D.visible] is set to [code]true[/code].
|
||||
</description>
|
||||
<tutorials>
|
||||
</tutorials>
|
||||
<members>
|
||||
<member name="enable_mode" type="int" setter="set_enable_mode" getter="get_enable_mode" enum="VisibleOnScreenEnabler3D.EnableMode" default="0">
|
||||
Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED].
|
||||
</member>
|
||||
<member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")">
|
||||
The path to the target node, relative to the [VisibleOnScreenEnabler3D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler3D] is inside the scene tree) and every time the [VisibleOnScreenEnabler3D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected.
|
||||
</member>
|
||||
</members>
|
||||
<constants>
|
||||
<constant name="ENABLE_MODE_INHERIT" value="0" enum="EnableMode">
|
||||
Corresponds to [constant Node.PROCESS_MODE_INHERIT].
|
||||
</constant>
|
||||
<constant name="ENABLE_MODE_ALWAYS" value="1" enum="EnableMode">
|
||||
Corresponds to [constant Node.PROCESS_MODE_ALWAYS].
|
||||
</constant>
|
||||
<constant name="ENABLE_MODE_WHEN_PAUSED" value="2" enum="EnableMode">
|
||||
Corresponds to [constant Node.PROCESS_MODE_WHEN_PAUSED].
|
||||
</constant>
|
||||
</constants>
|
||||
</class>
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<class name="VisibleOnScreenNotifier2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
||||
<brief_description>
|
||||
Detects when the node extents are visible on screen.
|
||||
A rectangular region of 2D space that detects whether it is visible on screen.
|
||||
</brief_description>
|
||||
<description>
|
||||
The VisibleOnScreenNotifier2D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a viewport.
|
||||
If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler2D] instead.
|
||||
[b]Note:[/b] VisibleOnScreenNotifier2D uses the render culling code to determine whether it's visible on screen, which also means that its [member CanvasItem.visible] must be [code]true[/code] to work correctly.
|
||||
[VisibleOnScreenEnabler2D] represents a rectangular region of 2D space. When any part of this region becomes visible on screen or in a viewport, it will emit a [signal screen_entered] signal, and likewise it will emit a [signal screen_exited] signal when no part of it remains visible.
|
||||
If you want a node to be enabled automatically when this region is visible on screen, use [VisibleOnScreenEnabler2D].
|
||||
[b]Note:[/b] [VisibleOnScreenNotifier2D] uses the render culling code to determine whether it's visible on screen, so it won't function unless [member CanvasItem.visible] is set to [code]true[/code].
|
||||
</description>
|
||||
<tutorials>
|
||||
<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link>
|
||||
|
|
@ -16,7 +16,7 @@
|
|||
<return type="bool" />
|
||||
<description>
|
||||
If [code]true[/code], the bounding rectangle is on the screen.
|
||||
[b]Note:[/b] It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return [code]false[/code] right after it is instantiated, even if it will be on screen in the draw pass.
|
||||
[b]Note:[/b] It takes one frame for the [VisibleOnScreenNotifier2D]'s visibility to be determined once added to the scene tree, so this method will always return [code]false[/code] right after it is instantiated, before the draw pass.
|
||||
</description>
|
||||
</method>
|
||||
</methods>
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<class name="VisibleOnScreenNotifier3D" inherits="VisualInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
||||
<brief_description>
|
||||
Detects approximately when the node is visible on screen.
|
||||
A box-shaped region of 3D space that detects whether it is visible on screen.
|
||||
</brief_description>
|
||||
<description>
|
||||
The VisibleOnScreenNotifier3D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a [Camera3D]'s view.
|
||||
If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler3D] instead.
|
||||
[b]Note:[/b] VisibleOnScreenNotifier3D uses the render culling code to determine whether it's visible on screen, which also means that its [member Node3D.visible] must be [code]true[/code] to work correctly.
|
||||
[VisibleOnScreenEnabler3D] represents a box-shaped region of 3D space. When any part of this region becomes visible on screen or in a [Camera3D]'s view, it will emit a [signal screen_entered] signal, and likewise it will emit a [signal screen_exited] signal when no part of it remains visible.
|
||||
If you want a node to be enabled automatically when this region is visible on screen, use [VisibleOnScreenEnabler3D].
|
||||
[b]Note:[/b] [VisibleOnScreenNotifier3D] uses an approximate heuristic that doesn't take walls and other occlusion into account, unless occlusion culling is used. It also won't function unless [member Node3D.visible] is set to [code]true[/code].
|
||||
</description>
|
||||
<tutorials>
|
||||
</tutorials>
|
||||
|
|
@ -14,25 +14,25 @@
|
|||
<method name="is_on_screen" qualifiers="const">
|
||||
<return type="bool" />
|
||||
<description>
|
||||
If [code]true[/code], the bounding box is on the screen.
|
||||
[b]Note:[/b] It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return [code]false[/code] right after it is instantiated, even if it will be on screen in the draw pass.
|
||||
Returns [code]true[/code] if the bounding box is on the screen.
|
||||
[b]Note:[/b] It takes one frame for the [VisibleOnScreenNotifier3D]'s visibility to be assessed once added to the scene tree, so this method will always return [code]false[/code] right after it is instantiated.
|
||||
</description>
|
||||
</method>
|
||||
</methods>
|
||||
<members>
|
||||
<member name="aabb" type="AABB" setter="set_aabb" getter="get_aabb" default="AABB(-1, -1, -1, 2, 2, 2)">
|
||||
The VisibleOnScreenNotifier3D's bounding box.
|
||||
The [VisibleOnScreenNotifier3D]'s bounding box.
|
||||
</member>
|
||||
</members>
|
||||
<signals>
|
||||
<signal name="screen_entered">
|
||||
<description>
|
||||
Emitted when the VisibleOnScreenNotifier3D enters the screen.
|
||||
Emitted when the [VisibleOnScreenNotifier3D] enters the screen.
|
||||
</description>
|
||||
</signal>
|
||||
<signal name="screen_exited">
|
||||
<description>
|
||||
Emitted when the VisibleOnScreenNotifier3D exits the screen.
|
||||
Emitted when the [VisibleOnScreenNotifier3D] exits the screen.
|
||||
</description>
|
||||
</signal>
|
||||
</signals>
|
||||
|
|
|
|||
Loading…
Reference in a new issue