manual/sculpt_paint/sculpting/introduction/gesture_tools.rst

@@ -0,0 +1,77 @@
+=============
+Gesture Tools
+=============
+
+Separate from brushes and filters, Sculpt mode also has a set of tools that perform actions to a drawn
+selection area. These tools are similar to the selection tools (e.g. :ref:`box selection <tool-select-box>` 
+and :ref:`lasso selection <tool-select-lasso>` in other areas of Blender).
+
+These tools do not provide a selection of elements that are then modified, they directly modify the underlying 
+mesh.
+
+.. _gesture-tool-box:
+
+Box Gestures
+============
+
+Dragging creates a rectangular area defined by where :kbd:`LMB` was pressed and where :kbd:`LMB` is released.
+
+Controls
+--------
+
+Move :kbd:`Spacebar`
+   Hold to reposition the selection area.
+
+.. _gesture-tool-lasso:
+
+Lasso Gestures
+==============
+
+Dragging creates a freeform area that follows the cursor defined by where :kbd:`LMB` was pressed and where :kbd:`LMB`
+is released.
+
+Controls
+--------
+
+Move :kbd:`Spacebar`
+   Hold to reposition the selection area.
+
+.. _gesture-tool-line:
+
+Line Gestures
+=============
+
+Dragging creates a line. The resulting action acts upon everything on the highlighed side of the line. The area acted
+upon is extended in both directions of the viewport.
+
+Controls
+--------
+
+Flip :kbd:`F`
+   Toggles the side of the line that the tool affects.
+Snap :kbd:`Ctrl`
+   Hold to constrain the rotation of the line to user-specified intervals. Defaults to 5 degree increments, 
+   customizable via the Snapping menu indicated by the magnet icon in the header.
+Move :kbd:`Spacebar`
+   Hold to reposition the line.
+
+.. _gesture-tool-polyline:
+
+Tool Settings
+-------------
+
+Limit to Segment
+   The affected area will not extend the length of the drawn line.
+   This helps defining a smaller area instead of extending the line infinitely long.
+
+Polyline Gestures
+=================
+
+Clicking places a point in the viewport. Each time :kbd:`LMB` is pressed, a new point of the polygon is created.
+Pressing :kbd:`LMB` on the starting point or pressing :kbd:`Return` closes the selection area. 
+
+Controls
+--------
+
+Move :kbd:`Spacebar`
+   Hold to reposition the selection area.

manual/sculpt_paint/sculpting/introduction/index.rst

@@ -7,6 +7,7 @@
 
    general.rst
    brush.rst
+   gesture_tools.rst
    visibility_masking_face_sets.rst
    filters.rst
    transforming.rst

manual/sculpt_paint/sculpting/introduction/visibility_masking_face_sets.rst

@@ -37,11 +37,8 @@ Masks
 .. figure:: /images/sculpt-paint_sculpting_editing_mask_example.jpg
 
 A mask is used to control which vertices of the mesh are influenced by sculpting and painting.
-The mask can for example be created/edited via the :doc:`Mask Brush </sculpt_paint/sculpting/tools/mask>`,
+The mask can for example be created/edited via the :doc:`/sculpt_paint/sculpting/tools/mask_tools`
-:doc:`Box Mask </sculpt_paint/sculpting/tools/box_mask>`,
+and :doc:`Mask by Color </sculpt_paint/sculpting/tools/mask_by_color>` tool.
-:doc:`Lasso Mask </sculpt_paint/sculpting/tools/lasso_mask>`,
-:doc:`Line Mask </sculpt_paint/sculpting/tools/line_mask>`
-and :doc:`Mask by Color </sculpt_paint/sculpting/tools/mask_by_color>` tools.
 
 Internally, masks are stored using the ``sculpt_mask`` :doc:`/modeling/geometry_nodes/attributes_reference`.
 

manual/sculpt_paint/sculpting/toolbar.rst

@@ -162,16 +162,11 @@ Gesture Tools
 .. figure:: /images/sculpt-paint_sculpting_toolbar_gestures.png
    :align: right
 
-General gesture tools to apply an operation via box, lasso and line shapes.
+General gesture tools to apply an operation via box, lasso, line and polyline shapes. 
+See :doc:`/sculpt_paint/sculpting/introduction/gesture_tools` for more information.
 
-:doc:`/sculpt_paint/sculpting/tools/box_mask`
+:doc:`/sculpt_paint/sculpting/tools/mask_tools`
-   Create a mask via a box gesture.
+   Create a mask via a gesture.
-
-:doc:`/sculpt_paint/sculpting/tools/lasso_mask`
-   Create a mask via a lasso gesture.
-
-:doc:`/sculpt_paint/sculpting/tools/line_mask`
-   Create a mask via on one side of a drawn line.
 
 Box Hide
    Hides/Shows geometry via a box gesture.

manual/sculpt_paint/sculpting/tools/box_mask.rst

@@ -1,22 +0,0 @@
-
-********
-Box Mask
-********
-
-.. reference::
-
-   :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Box Mask`
-
-Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>`
-based on a :ref:`box selection <tool-select-box>`.
-Hold :kbd:`Ctrl` to subtract from the mask instead.
-
-This tool is also accessible as a :ref:`shortcut operator <bpy.ops.paint.mask_box_gesture>` on :kbd:`B`.
-
-
-Tool Settings
-=============
-
-Front Faces Only
-   Only creates a mask on the faces that face towards the view.

manual/sculpt_paint/sculpting/tools/index.rst

@@ -38,9 +38,7 @@
    multires_displacement_smear.rst
    paint.rst
    smear.rst
-   box_mask.rst
+   mask_tools.rst
-   lasso_mask.rst
-   line_mask.rst
    box_face_set.rst
    lasso_face_set.rst
    box_trim.rst

manual/sculpt_paint/sculpting/tools/lasso_mask.rst

@@ -1,23 +0,0 @@
-
-**********
-Lasso Mask
-**********
-
-.. reference::
-
-   :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Lasso Mask`
-
-Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>`
-based on a :ref:`lasso selection <tool-select-lasso>`.
-Hold :kbd:`Ctrl` to subtract from the mask instead.
-
-This tool is also accessible as a :ref:`shortcut operator <bpy.ops.paint.mask_box_gesture>` on
-:kbd:`Shift-Ctrl-LMB` drag.
-
-
-Tool Settings
-=============
-
-Front Faces Only
-   Only creates a mask on the faces that face towards the view.

manual/sculpt_paint/sculpting/tools/line_mask.rst

@@ -1,48 +0,0 @@
-
-*********
-Line Mask
-*********
-
-.. reference::
-
-   :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Line Mask`
-
-This tool creates a :doc:`Mask </sculpt_paint/sculpting/editing/mask>`
-across one side of a drawn line.
-The affected area is visualized by the shaded side of the line.
-
-
-Usage
-=====
-
-Use the tool by:
-
-#. Orient the 3D Viewport to define the direction in depth.
-#. :kbd:`LMB` and hold while moving the cursor to define direction of the line mask.
-#. Adjust the operation with extra *Controls* shortcuts.
-#. Release :kbd:`LMB` to confirm.
-
-Hold :kbd:`Ctrl` to subtract from the mask instead.
-
-
-Controls
-========
-
-Flip :kbd:`F`
-   Changes the side of the line that the tool creates a mask.
-Snap :kbd:`Ctrl`
-   Constrains the rotation of the line to 15 degree intervals.
-Move :kbd:`Ctrl-Spacebar`
-   Reposition the line.
-
-
-Tool Settings
-=============
-
-Front Faces Only
-   Only creates a mask on the faces that face towards the view.
-
-Limit to Segment
-   The affected area will not extend the length of the drawn line.
-   This helps defining a smaller area instead of extending the line infinitely long.

manual/sculpt_paint/sculpting/tools/mask_tools.rst

@@ -0,0 +1,73 @@
+
+******************
+Mask Gesture Tools
+******************
+
+.. reference::
+
+   :Mode:      Sculpt Mode
+   :Tool:      :menuselection:`Toolbar --> Box Mask`
+
+Mask gesture tools apply a constant value to all selected vertices within the selection area.
+By default, these tools fully mask each vertex. Holding :kbd:`Ctrl` while performing the selection
+clears the mask.
+
+All mask gesture tools can be activated in the Toolbar and are comprised of the following:
+
+.. _tool-box-mask:
+
+Box Mask
+========
+
+.. reference::
+
+   :Mode:      Sculpt Mode
+   :Tool:      :menuselection:`Toolbar --> Box Mask`
+   :Shortcut:  :kbd:`B`
+
+
+Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>` based on a
+:ref:`box gesture <gesture-tool-box>`.
+
+.. _tool-lasso-mask:
+
+Lasso Mask
+==========
+
+.. reference::
+
+   :Mode:      Sculpt Mode
+   :Tool:      :menuselection:`Toolbar --> Lasso Mask`
+
+Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>` based on a
+:ref:`lasso gesture <gesture-tool-lasso>`.
+
+.. _tool-line-mask:
+
+Line Mask
+=========
+
+.. reference::
+
+   :Mode:      Sculpt Mode
+   :Tool:      :menuselection:`Toolbar --> Line Mask`
+
+Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>` based on a
+:ref:`line gesture <gesture-tool-line>`
+
+Polyline Mask
+=============
+
+.. reference::
+
+   :Mode:      Sculpt Mode
+   :Tool:      :menuselection:`Toolbar --> Polyline Mask`
+
+Creates a new :doc:`Mask </sculpt_paint/sculpting/editing/mask>` based on a
+:ref:`line gesture <gesture-tool-polyline>`
+
+Common Options
+==============
+
+Front Faces Only
+   Only creates a mask on the faces that face towards the view.