manual/sculpt_paint/brush/brush_management.rst

@@ -0,0 +1,74 @@
+****************
+Brush Management
+****************
+
+Brush assets are stored in :doc:`asset libraries </files/asset_libraries/introduction>` to make them accesible from
+any Blender session. There are two ways of managing brush assets:
+
+- :ref:`Asset Operators <brush-management-utility-operators>`: Create and update brush assets using utility operators
+  from any Blender file. Storage is managed by Blender. Convenient for simple "on the fly" management of personal brush
+  asset libraries.
+- :ref:`Manual Storage <brush-management-manual>`: Create and update brush assets by opening blend files within asset
+  libraries, and managing brush asset data-blocks in there. Useful for careful curation of asset libraries, especially
+  to prepare them for sharing with others.
+
+.. _brush-management-utility-operators:
+
+Asset Operators
+===============
+
+.. reference::
+
+   :Mode:      All Paint Modes
+   :Panel:     :menuselection:`Sidebar --> Tool --> Brush Asset`
+               :menuselection:`Properties --> Tool --> Brush Asset`
+   :Menu:      :menuselection:`Asset Shelf --> Context Menu`
+
+.. figure:: /images/sculpt_paint_brush_brush-management_asset-operators.png
+   :align: right
+   :width: 300
+
+   Brush Asset panel in the tool settings showing asset operators.
+
+Duplicate Asset... (Duplicate icon)
+   Creates a copy of the currently active brush as asset, and activates it. A popup is spawned to input some settings
+   to use:
+
+   Name
+      A custom name to use for the new brush
+   Library
+      Choose an Asset Library to store the new brush asset in. The available asset libraries are configured
+      :ref:`in the Preferences <bpy.types.UserAssetLibrary>`.
+   Catalog
+      Choose an Asset Catalog to assign the brush asset to. Entering a non-existent name/path will create a new catalog
+      accordingly.
+
+Delete Asset
+   Permanently remove this brush asset from the Asset Library it is stored in. This cannot be undone, so a popup will
+   ask for confirmation.
+Edit Metadata...
+   Spawns a popup to change some of the available :ref:`asset metadata <editing-asset-metadata>` fields.
+
+   Catalog
+      Choose an Asset Catalog to assign the brush asset to. Entering a non-existent name/path will create a new catalog
+      accordingly.
+   Author
+      See :ref:`Asset Author <bpy.types.AssetMetaData.description>`
+   Description
+      See :ref:`Asset Description <bpy.types.AssetMetaData.description>`
+Edit Preview Image...
+   Opens a window with the File Browser to select an image for the asset preview.
+Update Asset
+   Saves any changes made to the active brush to the asset library.
+Revert to Asset
+   Discards any unsaved changes made to the brush asset.
+
+
+.. _brush-management-manual:
+
+Manual Storage
+==============
+
+It is also possible to manually manage brushes in blend-files. By marking brushes as assets and saving the file in an
+Asset Library, they become available from any Blender session. This gives full control over managing storage, and is
+particularly useful for curating asset libraries that can be shared with others.

manual/sculpt_paint/brush/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    introduction.rst
+   brush_management.rst
 
 
 Brush Settings

manual/sculpt_paint/brush/introduction.rst

@@ -1,3 +1,6 @@
+.. _bpy.types.Brush:
+.. _bpy.ops.brush:
+.. _bpy.types.UnifiedPaintSettings:
 
 ************
 Introduction
@@ -8,15 +11,19 @@ Introduction
 
    Brush cursor.
 
-Brushes are the main way of interacting with any painting and sculpting mode.
+Brushes are the main way of interacting with any painting and sculpting mode. By click & dragging in the 3D Viewport
-While click & dragging in the 3D Viewport it will create a :doc:`stroke </sculpt_paint/brush/stroke>`
+(or the Image Editor when using :doc:`Texture Paint </sculpt_paint/texture_paint/index>`), the active brush creates a
-and apply an effect depending on the used brush and brush/tool settings.
+:doc:`stroke </sculpt_paint/brush/stroke>` with a certain effect, depending on the used brush settings. Typically
+Brushes have a preview image and a name that indicate the effect they create. Brushes are only used while the Brush
+Tool is active.
+
 
 .. tip::
 
    It is highly recommended to use a :ref:`Graphics Tablet <hardware-tablet>`
    for a better brush feel and additional features.
 
+.. _brush-introduction-accessing-brushes:
 
 Accessing Brushes
 =================
@@ -63,65 +70,13 @@ Brush Assets
 ============
 
 Brushes are used as assets, and stored in :doc:`asset libraries </files/asset_libraries/introduction>`. This makes the
-brushes shared across project files. All available brush assets can be displayed in the Asset Browser, which also
+brushes shared across project files. All available brush assets can be displayed in the
-provides ways to organize them.
+:doc:`Asset Browser </editors/asset_browser>`, which also provides ways to organize them.
 
 Blender comes bundled with a number of brushes in the `Essentials` asset library. These can be customized into all
-kinds of custom brushes by duplicating them (see :doc:`Brush Editing<brush-editing>`).
+kinds of custom brushes by duplicating them (see :doc:`Brush Editing<brush_management>`).
 
 While it's possible to have brush data-blocks that are local to the file and not marked as assets, such brushes cannot
 be activated for actual painting or sculpting. Use the `Mark as Asset` operator to make them brush assets that can be
 activated.
 
-
-.. _bpy.types.Brush:
-.. _bpy.ops.brush:
-.. _bpy.types.UnifiedPaintSettings:
-
-Brush Editing
-=============
-
-.. reference::
-
-   :Mode:      All Paint Modes
-   :Panel:     :menuselection:`Sidebar --> Tool --> Brushes`
-
-For painting/sculpting modes each brush type is exposed as a tool in the toolbar.
-The brush on the other hand is a saved preset of all the brush settings, including a name and thumbnail.
-
-All these settings can be found and changed here in the tool setting (brush, texture, stroke, falloff & cursor).
-
-.. figure:: /images/sculpt-paint_brush_brush_data-block-menu.png
-   :align: right
-
-   Brush panel in the tool settings.
-
-Brushes
-   Clicking on the brush thumbnail will open the :ref:`ui-data-block` to select a brush.
-
-   Add Brush (Duplicate icon)
-      When you add a brush, the new brush is a duplicate of the current one.
-   Fake User (Shield icon)
-      Enabling this button will ensure that the brush will not be deleted,
-      even if it is not used by any tool.
-   Unlink Data-Block (Cross icon)
-      Unassign the brush from the active tool.
-      Hold :kbd:`Shift` to remove the brush from all users,
-      so it will be deleted upon reloading the file or purging orphan data.
-
-   Brush Specials (Arrow button)
-      Enabled Modes
-         Enable the brush to be used in different (even multiple) modes.
-         For example, the exact same brushes are used in both Weight Paint
-         and Vertex Paint mode.
-      Tool Selection
-         Transfer the brush preset to be used by a different brush type.
-      Reset Brush
-         Reset all brush settings to the default values of the current brush type.
-
-.. _bpy.types.Brush.use_custom_icon:
-.. _bpy.types.Brush.icon_filepath:
-
-   Custom Icon
-      Define a custom brush thumbnail from an image file.
-