[Bf-docboard-svn] bf-manual: [8656] branches/blender-3.0-release/blender_docs/manual: Initial checkin of Asset Browser docs
Sybren A. Stüvel
noreply at blender.org
Mon Nov 22 18:16:21 CET 2021
Revision: 8656
https://developer.blender.org/rBM8656
Author: sybren
Date: 2021-11-22 18:16:21 +0100 (Mon, 22 Nov 2021)
Log Message:
-----------
Initial checkin of Asset Browser docs
Initial version of the Asset Browser documentation. Not yet
complete, needs more screenshots, links, description of the
UI elements of the asset browser, and the entire pose library.
Modified Paths:
--------------
branches/blender-3.0-release/blender_docs/manual/editors/asset_browser.rst
branches/blender-3.0-release/blender_docs/manual/files/index.rst
Added Paths:
-----------
branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/
branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/catalogs.rst
branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/index.rst
branches/blender-3.0-release/blender_docs/manual/images/asset-browser-catalogs.png
branches/blender-3.0-release/blender_docs/manual/images/asset-catalog-tree.png
Modified: branches/blender-3.0-release/blender_docs/manual/editors/asset_browser.rst
===================================================================
--- branches/blender-3.0-release/blender_docs/manual/editors/asset_browser.rst 2021-11-22 02:47:13 UTC (rev 8655)
+++ branches/blender-3.0-release/blender_docs/manual/editors/asset_browser.rst 2021-11-22 17:16:21 UTC (rev 8656)
@@ -1,11 +1,76 @@
+.. _editors-asset-browser:
*************
Asset Browser
*************
-Todo Introduction.
+This section describes the *Asset Browser*. For general information on Blender's
+asset library system, how to :ref:`create <asset-create>` and :ref:`edit <asset-edit>`
+assets, and design choices, see :doc:`/files/asset_libraries/index`.
+*The Asset Browser was introduced in Blender 3.0, and will be improved and
+expanded over multiple subsequent releases.*
+.. _assets-using:
+
+Using Assets
+=====================
+
+As a general rule, **an asset can be used by dragging it from the Asset Browser
+to the desired location**. Objects and Worlds can be dragged from the asset
+browser into the scene, Materials can be dragged onto the object that should use
+them. The use of pose assets is described in :ref:`pose-library-using`.
+
+There are several things that can happen when an asset is used, depending on the
+**Import Type** configuration of the asset browser:
+
+Link
+ *Same as File > Link...*
+
+ The asset will be linked to the current blend file, and thus be read-only.
+ Subsequent changes to the asset file will be reflected in all files that link
+ it in.
+
+Append
+ *Same as File > Append...*
+
+ All of the asset and all its dependencies will be appended to the current
+ file. Dragging a material into the scene three times will result in three
+ independent copies. Dragging an object into the scene three times will also
+ result in three independent copies.
+
+ "Dependencies" in this case means everything the asset refers to. For an
+ object, this could be its mesh and materials, but also other objects used by
+ modifiers, constraints, or drivers.
+
+ Since the file now has its own copy of the asset, subsequent changes to the
+ asset file will not be reflected in the file it's appended to.
+
+Append (Reuse Data)
+ *Specific to the asset browser.*
+
+ The first time an asset is used, it will be appended, including its
+ dependencies, just like described above. However, Blender will keep track of
+ where it came from, and the next time the asset is used, as much data as
+ possible will be reused. Dragging a material into the scene three times will
+ only load it once, and just assign the same material three times. Dragging an
+ object into the scene three times will create three copies of the object, but
+ all copies will share their mesh data, materials, etc.
+
+ Since the file now has its own copy of the asset, subsequent changes to the
+ asset file will not be reflected in the file it's appended to.
+
+
+Note that all regular Blender operations are available after the asset has been
+added to the current file. For example, you could choose to link an Object to
+the scene; this will also link its Mesh and its Materials. Subsequently you can
+make the Object itself local (Object > Relations > Make Local... > Selected
+Objects), while keeping the Mesh and Materials linked to the asset files. This
+will result in a local, and thus editable, Object, and keep the Mesh and
+Materials automatically up to date with any changes in the asset library.
+
+
+
Interface
=========
Added: branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/catalogs.rst
===================================================================
--- branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/catalogs.rst (rev 0)
+++ branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/catalogs.rst 2021-11-22 17:16:21 UTC (rev 8656)
@@ -0,0 +1,146 @@
+.. _asset-catalogs:
+
+################
+ Asset Catalogs
+################
+
+:term:`Asset Catalogs` help you to organise your assets. They look a little bit
+like directories on disk, but they're totally independent of the location of
+your .blend files. Assign each asset in a .blend file to its own catalog, or
+have one big catalog with all the assets of all the .blend files combined. It's
+all up to you.
+
+For more technical information, see `Asset Catalogs on the Blender
+Wiki <https://wiki.blender.org/wiki/Source/Architecture/Asset_System/Catalogs>`_.
+
+.. figure:: /images/asset-browser-catalogs.png
+ :width: 640px
+
+ Example filesystem and catalog structures.
+
+
+The Home Location of Assets
+==============================
+
+There can be as many catalogs as you want, but **an asset can be assigned to a
+single catalog** at a time. This is similar to a file system, where a file is
+only in one directory (ignoring advanced things like symbolic links).
+
+Catalogs themselves can be nested and moved around by dragging & dropping.
+Moving a catalog will not modify the assets in it; they will simply move along
+to the new location of the catalog.
+
+Selecting a catalog in the asset browser will show all assets in that catalog
+and in child catalogs. So, in the example above, selecting
+`Characters/Ellie/Poses` will also show assets from
+`Characters/Ellie/Poses/Head` and `Characters/Ellie/Poses/Hands`.
+
+Assigning an Asset
+==============================
+
+To assign an action to a catalog, just drag the asset on top of the catalog.
+
+Components of a Catalog
+==============================
+
+Each catalog consists of a *catalog path*, a *UUID*, and a *simple name*.
+Normally you'd only deal with the catalog path; the rest is for internal Blender
+use and/or for emergency situations.
+
+Catalog Path
+------------------------------
+
+The path of a catalog determines where in the catalog hierarchy the catalog is
+shown. Examples are `Characters/Ellie/Poses/Hand` or `Kitbash/City/Skyscrapers`,
+which would result in the following catalog tree. The highlighted catalog has
+path `Characters/Ellie/Poses/Hand`.
+
+.. figure:: /images/asset-catalog-tree.png
+ :width: 257px
+
+ Example tree of asset catalogs
+
+
+UUID
+------------------------------
+
+Each catalog has a `UUID <https://en.wikipedia.org/wiki/Universally_unique_identifier>`_,
+which is normally hidden from the user interface (enable Developer Extras and
+the experimental Asset Debug Info option to see them). This is what is stored in
+the asset, and what determines the "identity" of the catalog. As a result, a
+catalog can be renamed or moved around (i.e. you can change its path), and all
+assets that are contained in it will move along with it. This only requires a
+change to the catalog itself, and not to any asset blend file.
+
+Simple Name
+------------------------------
+
+Each catalog has an optional *simple name*. This name is stored along with the
+UUID in each asset. The purpose is to make it possible for humans to recognise
+the catalog the asset was assigned to, even when the *catalog definition file*
+(see below) is lost.
+
+Like the UUID, the simple name is normally hidden from the user interface.
+Enable Developer Extras in the interface preferences to make it visible in the
+asset browser.
+
+
+.. _asset-catalog-definition-file:
+
+Catalog Definition Files
+==============================
+
+
+Asset catalogs are stored in Catalog Definition Files (CDFs). Blender 3.0
+supports a single CDF per asset library. It is stored in
+`blender_assets.cats.txt` in the root directory of the asset library. If the
+file does not exist, Blender will create it when the catalogs are saved.
+
+Which File To Write To
+------------------------------
+
+Asset catalogs can be saved independently of the blend file; the catalog editor
+has its own "Save" button.
+
+
+Format
+------------------------------
+
+Catalog Definition Files (CDFs) are relatively simple text files, encoded in
+UTF-8. Each CDF consists of a version indicator, and a line of text per catalog.
+Each catalog line is colon-separated, of the form `{UUID}:{path}:{simple name}`.
+
+Example
+------------------------------
+
+This is an example of a valid catalog definition file::
+
+ # This is an Asset Catalog Definition file for Blender.
+ #
+ # Empty lines and lines starting with `#` will be ignored.
+ # The first non-ignored line should be the version indicator.
+ # Subsequent lines are of the format "CATALOG_UUID:catalog/path/for/assets:simple catalog name"
+
+ VERSION 1
+
+ 313ea471-7c81-4de6-af81-fb04c3535d0e:catalog/without/simple/name:
+ ee9c7b60-02f1-4058-bed6-539b8d2a6d34:character/Ellie/poselib:character-Ellie-poselib
+ cd66bf52-58f4-45cb-a4e2-dc0e0ee8f3fe:character/Ellie/poselib:character-Ellie
+ 4eb44ec6-3424-405b-9782-ca006953e799:character/Ellie/poselib/white space:character-Ellie-poselib-white space
+ b63ed357-2511-4b96-8728-1b5a7093824c:character/Ružena/poselib:Ružena pose library
+ dcdee4df-926e-4d72-b995-33106983bb9a:character/Ružena/poselib/face:Ružena face
+ fb698f2e-9e2b-4146-a539-3af292d44899:character/Ružena/poselib/hand:Ružena hands
+
+
+Valid Catalog Paths
+------------------------------
+
+Catalog paths follow the following rules:
+
+- All paths are absolute; there is no difference between `/a/b` and `a/b`.
+- Only `/` as separator (no `\\`; think less filesystem path and more URL).
+- Not empty (it's required for a valid catalog).
+- No empty components (so not `a//b`; `a/b` is fine).
+- Invalid characters: `:`, `\\`.
+- Paths are always interpreted as UTF-8.
+
Property changes on: branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/catalogs.rst
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/index.rst
===================================================================
--- branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/index.rst (rev 0)
+++ branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/index.rst 2021-11-22 17:16:21 UTC (rev 8656)
@@ -0,0 +1,243 @@
+****************
+Asset Libraries
+****************
+
+This section describes Blender's Asset Library system. It was introduced in
+Blender 3.0, and will be improved and expanded over multiple subsequent
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-docboard-svn
mailing list