From cfb555a08175c811ea06a43ea320b81a2c90554a Mon Sep 17 00:00:00 2001 From: jfons Date: Wed, 23 Jun 2021 16:49:50 +0200 Subject: Node3D gizmo improvements * Clean-up of node_3d_editor_plugin.{h,cpp}: removed unused code, fixed some bugs. * Moved node_3d_editor_gizmos.{h,cpp} to editor/plugins. * Added support for multiple gizmos per node. This means custom gizmos will no longer override the built-in ones and that multiple gizmos can be used in more complex nodes. * Added support for handle IDs. When adding handles to a gizmo, an ID can be specified for each one, making it easier to work with gizmos that have a variable number of handles. * Added support for subgizmos, selectable elements that can be transformed without needing a node of their own. By overriding _subgizmo_intersect_frustum() and/or _subgizmo_intersect_ray() gizmos can define which subgizmos should be selected on a region or click selection. Subgizmo transformations are applied using get/set/commit virtual methods, similar to how handles work. --- doc/classes/EditorNode3DGizmo.xml | 127 +++++++++++++++++++++++++------- doc/classes/EditorNode3DGizmoPlugin.xml | 93 +++++++++++++++++++---- doc/classes/Node3D.xml | 39 ++++++++-- 3 files changed, 213 insertions(+), 46 deletions(-) (limited to 'doc/classes') diff --git a/doc/classes/EditorNode3DGizmo.xml b/doc/classes/EditorNode3DGizmo.xml index 221b5e44d6..d4d1e4a652 100644 --- a/doc/classes/EditorNode3DGizmo.xml +++ b/doc/classes/EditorNode3DGizmo.xml @@ -1,10 +1,10 @@ - Custom gizmo for editing Node3D objects. + Gizmo for editing Node3D objects. - Custom gizmo that is used for providing custom visualization and editing (handles) for Node3D objects. See [EditorNode3DGizmoPlugin] for more information. + Gizmo that is used for providing custom visualization and editing (handles and subgizmos) for Node3D objects. Can be overridden to create custom gizmos, but for simple gizmos creating a [EditorNode3DGizmoPlugin] is usually recommended. @@ -12,64 +12,119 @@ - + - Commit a handle being edited (handles must have been previously added by [method add_handles]). - If the [code]cancel[/code] parameter is [code]true[/code], an option to restore the edited value to the original is provided. + Override this method to commit a handle being edited (handles must have been previously added by [method add_handles]). This usually means creating an [UndoRedo] action for the change, using the current handle value as "do" and the [code]restore[/code] argument as "undo". + If the [code]cancel[/code] argument is [code]true[/code], the [code]restore[/code] value should be directly set, without any [UndoRedo] action. + + + + + + + + + + + + + Override this method to commit a group of subgizmos being edited (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). This usually means creating an [UndoRedo] action for the change, using the current transforms as "do" and the [code]restore[/code] transforms as "undo". + If the [code]cancel[/code] argument is [code]true[/code], the [code]restore[/code] transforms should be directly set, without any [UndoRedo] action. - + - Gets the name of an edited handle (handles must have been previously added by [method add_handles]). + Override this method to return the name of an edited handle (handles must have been previously added by [method add_handles]). Handles can be named for reference to the user when editing. - + - Gets actual value of a handle. This value can be anything and used for eventually undoing the motion when calling [method _commit_handle]. + Override this method to return the current value of a handle. This value will be requested at the start of an edit and used as the [code]restore[/code] argument in [method _commit_handle]. + + + + + + + + + Override this method to return the current transform of a subgizmo. This transform will be requested at the start of an edit and used as the [code]restore[/code] argument in [method _commit_subgizmos]. - + - Returns [code]true[/code] if the handle at index [code]index[/code] is highlighted by being hovered with the mouse. + Override this method to return [code]true[/code] whenever the given handle should be highlighted in the editor. - This function is called when the [Node3D] this gizmo refers to changes (the [method Node3D.update_gizmo] is called). + Override this method to add all the gizmo elements whenever a gizmo update is requested. It's common to call [method clear] at the beginning of this method and then add visual elements depending on the node's properties. - + - This function is used when the user drags a gizmo handle (previously added with [method add_handles]) in screen coordinates. - The [Camera3D] is also provided so screen coordinates can be converted to raycasts. + Override this method to update the node properties when the user drags a gizmo handle (previously added with [method add_handles]). The provided [code]point[/code] is the mouse position in screen coordinates and the [code]camera[/code] can be used to convert it to raycasts. + + + + + + + + + + + Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [code]transform[/code] is given in the Node3D's local coordinate system. + + + + + + + + + + + Override this method to allow selecting subgizmos using mouse drag box selection. Given a [code]camera[/code] and a [code]frustum[/code], this method should return which subgizmos are contained within the frustum. The [code]frustum[/code] argument consists of an [code]Array[/code] with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, which can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. + + + + + + + + + + + Override this method to allow selecting subgizmos using mouse clicks. Given a [code]camera[/code] and a [code]point[/code] in screen coordinates, this method should return which subgizmo should be selected. The returned value should be a unique subgizmo identifier, which can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. @@ -78,7 +133,7 @@ - Adds the specified [code]segments[/code] to the gizmo's collision shape for picking. Call this function during [method _redraw]. + Adds the specified [code]segments[/code] to the gizmo's collision shape for picking. Call this method during [method _redraw]. @@ -87,7 +142,7 @@ - Adds collision triangles to the gizmo for picking. A [TriangleMesh] can be generated from a regular [Mesh] too. Call this function during [method _redraw]. + Adds collision triangles to the gizmo for picking. A [TriangleMesh] can be generated from a regular [Mesh] too. Call this method during [method _redraw]. @@ -97,13 +152,15 @@ - + - + + + - Adds a list of handles (points) which can be used to deform the object being edited. - There are virtual functions which will be called upon editing of these handles. Call this function during [method _redraw]. + Adds a list of handles (points) which can be used to edit the properties of the gizmo's Node3D. The [code]ids[/code] argument can be used to specify a custom identifier for each handle, if an empty [code]Array[/code] is passed, the ids will be assigned automatically from the [code]handles[/code] argument order. + There are virtual methods which will be called upon editing of these handles. Call this method during [method _redraw]. @@ -118,7 +175,7 @@ - Adds lines to the gizmo (as sets of 2 points), with a given material. The lines are used for visualizing the gizmo. Call this function during [method _redraw]. + Adds lines to the gizmo (as sets of 2 points), with a given material. The lines are used for visualizing the gizmo. Call this method during [method _redraw]. @@ -126,14 +183,14 @@ - + - + - + - Adds a mesh to the gizmo with the specified [code]billboard[/code] state, [code]skeleton[/code] and [code]material[/code]. If [code]billboard[/code] is [code]true[/code], the mesh will rotate to always face the camera. Call this function during [method _redraw]. + Adds a mesh to the gizmo with the specified [code]material[/code], local [code]transform[/code] and [code]skeleton[/code]. Call this method during [method _redraw]. @@ -146,7 +203,7 @@ - Adds an unscaled billboard for visualization. Call this function during [method _redraw]. + Adds an unscaled billboard for visualization and selection. Call this method during [method _redraw]. @@ -170,6 +227,22 @@ Returns the Node3D node associated with this gizmo. + + + + + Returns a list of the currently selected subgizmos. Can be used to highlight selected elements during [method _redraw]. + + + + + + + + + Returns [code]true[/code] if the given subgizmo is currently selected. Can be used to highlight selected elements during [method _redraw]. + + diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml index 41c94cbbc6..10d6bd8bc8 100644 --- a/doc/classes/EditorNode3DGizmoPlugin.xml +++ b/doc/classes/EditorNode3DGizmoPlugin.xml @@ -14,7 +14,7 @@ - Override this method to define whether the gizmo can be hidden or not. Returns [code]true[/code] if not overridden. + Override this method to define whether the gizmos handled by this plugin can be hidden or not. Returns [code]true[/code] if not overridden. @@ -22,14 +22,31 @@ - + - Override this method to commit gizmo handles. Called for this plugin's active gizmos. + Override this method to commit a handle being edited (handles must have been previously added by [method EditorNode3DGizmo.add_handles] during [method _redraw]). This usually means creating an [UndoRedo] action for the change, using the current handle value as "do" and the [code]restore[/code] argument as "undo". + If the [code]cancel[/code] argument is [code]true[/code], the [code]restore[/code] value should be directly set, without any [UndoRedo] action. Called for this plugin's active gizmos. + + + + + + + + + + + + + + + Override this method to commit a group of subgizmos being edited (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). This usually means creating an [UndoRedo] action for the change, using the current transforms as "do" and the [code]restore[/code] transforms as "undo". + If the [code]cancel[/code] argument is [code]true[/code], the [code]restore[/code] transforms should be directly set, without any [UndoRedo] action. Called for this plugin's active gizmos. @@ -53,7 +70,7 @@ - + Override this method to provide gizmo's handle names. Called for this plugin's active gizmos. @@ -64,18 +81,29 @@ - + - Gets actual value of a handle from gizmo. Called for this plugin's active gizmos. + Override this method to return the current value of a handle. This value will be requested at the start of an edit and used as the [code]restore[/code] argument in [method _commit_handle]. Called for this plugin's active gizmos. - Override this method to set the gizmo's priority. Higher values correspond to higher priority. If a gizmo with higher priority conflicts with another gizmo, only the gizmo with higher priority will be used. - All built-in editor gizmos return a priority of [code]-1[/code]. If not overridden, this method will return [code]0[/code], which means custom gizmos will automatically override built-in gizmos. + Override this method to set the gizmo's priority. Gizmos with higher priority will have precedence when processing inputs like handles or subgizmos selection. + All built-in editor gizmos return a priority of [code]-1[/code]. If not overridden, this method will return [code]0[/code], which means custom gizmos will automatically get higher priority than built-in gizmos. + + + + + + + + + + + Override this method to return the current transform of a subgizmo. This transform will be requested at the start of an edit and used in the [code]restore[/code] argument in [method _commit_subgizmos]. Called for this plugin's active gizmos. @@ -92,10 +120,10 @@ - + - Gets whether a handle is highlighted or not. Called for this plugin's active gizmos. + Override this method to return [code]true[/code] whenever to given handle should be highlighted in the editor. Called for this plugin's active gizmos. @@ -111,7 +139,7 @@ - Callback to redraw the provided gizmo. Called for this plugin's active gizmos. + Override this method to add all the gizmo elements whenever a gizmo update is requested. It's common to call [method EditorNode3DGizmo.clear] at the beginning of this method and then add visual elements depending on the node's properties. @@ -119,14 +147,53 @@ - + - Update the value of a handle after it has been updated. Called for this plugin's active gizmos. + Override this method to update the node's properties when the user drags a gizmo handle (previously added with [method EditorNode3DGizmo.add_handles]). The provided [code]point[/code] is the mouse position in screen coordinates and the [code]camera[/code] can be used to convert it to raycasts. Called for this plugin's active gizmos. + + + + + + + + + + + + + Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [code]transform[/code] is given in the Node3D's local coordinate system. Called for this plugin's active gizmos. + + + + + + + + + + + + + Override this method to allow selecting subgizmos using mouse drag box selection. Given a [code]camera[/code] and a [code]frustum[/code], this method should return which subgizmos are contained within the frustum. The [code]frustum[/code] argument consists of an [code]Array[/code] with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, these identifiers can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. Called for this plugin's active gizmos. + + + + + + + + + + + + + Override this method to allow selecting subgizmos using mouse clicks. Given a [code]camera[/code] and a [code]point[/code] in screen coordinates, this method should return which subgizmo should be selected. The returned value should be a unique subgizmo identifier, which can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. Called for this plugin's active gizmos. diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml index 14e03a2186..9c05ed1ef6 100644 --- a/doc/classes/Node3D.xml +++ b/doc/classes/Node3D.xml @@ -13,6 +13,29 @@ https://github.com/godotengine/godot-demo-projects/tree/master/3d + + + + + + + Attach a gizmo to this [code]Node3D[/code]. + + + + + + + Clear all gizmos attached to this [code]Node3D[/code]. + + + + + + + Clears subgizmo selection for this node in the editor. Useful when subgizmo IDs become invalid after a property change. + + @@ -20,6 +43,13 @@ Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations. + + + + + Returns all the gizmos attached to this [code]Node3D[/code]. + + @@ -276,18 +306,15 @@ Changes the node's position by the given offset [Vector3] in local space. - + - Updates the [Node3DGizmo] of this node. + Updates all the [Node3DGizmo]s attached to this node. - - The [Node3DGizmo] for this node. Used for example in [EditorNode3DGizmo] as custom visualization and editing handles in Editor. - World3D space (global) [Transform3D] of this node. @@ -324,7 +351,7 @@ Node3D nodes receives this notification when their global transform changes. This means that either the current or a parent node changed its transform. - In order for [constant NOTIFICATION_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_transform]. The notification is also sent if the node is in the editor context and it has a valid gizmo. + In order for [constant NOTIFICATION_TRANSFORM_CHANGED] to work, users first need to ask for it, with [method set_notify_transform]. The notification is also sent if the node is in the editor context and it has at least one valid gizmo. Node3D nodes receives this notification when they are registered to new [World3D] resource. -- cgit v1.2.3