[Bf-docboard-svn] bf-manual: [8662] branches/blender-3.0-release/blender_docs/manual: Add pose library documentation

Tue Nov 23 11:22:45 CET 2021

Revision: 8662
          https://developer.blender.org/rBM8662
Author:   sybren
Date:     2021-11-23 11:22:44 +0100 (Tue, 23 Nov 2021)
Log Message:
-----------
Add pose library documentation

Still has a few TODOs for missing images. And there should be even more images.

Modified Paths:
--------------
    branches/blender-3.0-release/blender_docs/manual/animation/armatures/posing/editing/pose_library.rst
    branches/blender-3.0-release/blender_docs/manual/editors/asset_browser.rst
    branches/blender-3.0-release/blender_docs/manual/files/asset_libraries/index.rst

Modified: branches/blender-3.0-release/blender_docs/manual/animation/armatures/posing/editing/pose_library.rst
===================================================================

--- branches/blender-3.0-release/blender_docs/manual/animation/armatures/posing/editing/pose_library.rst	2021-11-23 03:49:06 UTC (rev 8661)
+++ branches/blender-3.0-release/blender_docs/manual/animation/armatures/posing/editing/pose_library.rst	2021-11-23 10:22:44 UTC (rev 8662)
@@ -4,25 +4,302 @@
 Pose Library
 ************
 
+This section describes the Pose Library, which is based on the
+:doc:`/editors/asset_browser`. For an overview of the asset system, see the
+:doc:`/files/asset_libraries/index` section.
+
+
+.. note::
+   At the moment of writing, the pose library is meant to be used in Pose Mode.
+   In other words, it only works when posing an armature, and not for general
+   object animation.
+
+
+What is a Pose Asset?
+=================================
+
+A *pose asset* is an Action that has been :ref:`marked as asset <asset-create>`,
+and that contains exactly **one frame of animation** data. Usually these are created
+via the Create Pose Asset button (see below), but any Action that is keyed on
+exactly one frame can be seen as pose asset.
+
+Each pose in the library is stored in its own Action data-block. This means that
+it can get its own name, its own preview icon, and can be organised in
+:doc:`/files/asset_libraries/catalogs`.
+
+
+Creating a Pose Library
+=================================
+
+A *pose library file* is typically a .blend file that is dedicated to poses. It
+can link in a character, props, etc., which can then not only be used to create
+the poses, but also for :ref:`rendering previews <poselib-preview-images>`.
+
+.. TODO::
+   ![Example library of poses from Sprite Fright](https://i.imgur.com/ZHIz1jL.png)
+
+
+Pose Creation via Action Editor
+--------------------------------------------
+
+To create a pose in the library from the Action Editor, **pose the character,
+select the relevant bones, and click the *Create Pose Asset* button**. This will
+create the new pose Action, which will contain keys for the current value of
+each bone’s location, rotation, scale, and bendy-bone properties.
+
+.. TODO::
+   https://i.imgur.com/QFlVvgW.jpg
+
+**The created Action is now assigned to the armature.** This makes it possible
+to inspect which bones are included and to tweak anything. In that respect, it’s
+an Action like any other, and you can add or remove keys as usual. Just make
+sure that the keys are all on the same frame, in order to keep this a “pose”
+instead of an “animation snippet”; the latter isn’t supported at the moment.
+
+True to its name, the *Create Pose Asset* button automatically marks the Action
+as Asset. Not only does this make it available in the pose library, it will also
+act as a *fake user* to ensure the Action isn’t lost after you unassign it from
+the armature.
+
+The *Create Pose Asset* button is also available in the *3D View side panel*.
+This button acts almost the same as the one in the Action Editor, except for one
+thing: it will not assign the newly created Action. Doing so would be invisible,
+as the pose doesn’t change and the name of the current Action is not shown in
+the viewport. The pose asset can still be renamed in the Asset Browser. There
+you can also click the *Assign Action* button to explicitly assign the selected
+pose asset as the armature’s active Action.
+
+.. note::
+   The **Create Pose Asset** button creates a new Action. To make sure that this
+   is actually visible in the user interface, so that you know that something
+   happened, it tries to make sure that the Asset Browser shows the newly
+   created pose asset. Because of this, it **requires that there is an Asset
+   Browser visible, and that it's set to show the Current File asset library**.
+
+   This is especially relevant to pose assets, compared to other assets. You
+   cannot mark an object as asset multiple times, but you can create ten pose
+   assets from the same character pose.
+
+
+Pose Creation from Existing Animation
+--------------------------------------------
+
+Animators eat and breathe time, so there is a fair chance that you already have
+some poses lined up on the timeline. Creating a pose asset from existing
+animation is pretty much the same as described above, with a few subtle
+differences:
+
+- Go to the frame with the pose you want to turn into an asset.
+- Select the relevant bones and click the **Create Pose Asset button** in the
+  Action Editor.
+- This creates an Action as before, but this time **it also includes any bone
+  property that was keyed on the current frame**. In other words: any bone
+  property (regular and custom) that’s displayed in yellow in the user interface
+  will be included in the pose asset. This makes it possible to also include
+  properties that control IK/FK switching, for example. As with the pose, the
+  current value is copied into the pose asset, and not the keyed value.
+- Blender remembers which action was previously assigned to the armature.
+- The new pose Action is assigned to the armature so you can give it a name and
+  inspect/adjust its contents.
+- Click **the “back” button** that appeared next to the Create Pose Asset button.
+  This **reassigns the previous Action**, so that you’re back at the animation you
+  had before.
+
+
+Pose Creation by Copying from Other File
+--------------------------------------------
+
+As described in :ref:`asset-libraries-design-limitations`, Blender only writes
+data to the currently open blend file. To copy a pose from some other file into
+a pose library file, see the following steps:
+
+- Pose the character and select the relevant bones.
+- Click the **Copy Pose as Asset button**, which is available in the Action Editor
+  as well as the 3D Viewport side panel. This will create the pose asset
+  (including its thumbnail) and store it in a temporary file somewhere.
+- Choose an already existing pose asset, and open its context menu (right-click
+  or press W, depending on your configuration). Click the **Open Blend File** option.
+- A new Blender process will start, and automatically open the asset library
+  file that contains the chosen pose. By the way, this works for all assets, not
+  just poses!
+- In the Asset Browser, click the **Paste As New Asset button**. This will load that
+  temporary file, and load all the assets it can find in there. In our case, it
+  will only find a single pose, but future versions of Blender may extend this
+  for other asset types. This is why the button is named so generically — it is
+  not pose-specific.
+- Give the pose a name, and click on the “refresh” button in the preview icon
+  panel to render a new preview if you want.
+- **Save the file and quit Blender**.
+- The original Blender is still running in the background and notices that the
+  new Blender has quit. It **automatically refreshes the asset browser** to show the
+  newly added pose.
+
+
+Automatically Assigned Catalog
+--------------------------------------------
+
+When you create a pose asset, Blender may automatically assign it to an asset
+catalog. This only works if there is an asset browser visible; Blender then
+assigns the pose asset to its active asset catalog. If there are multiple asset
+browsers open, it performs the following steps:
+
+- If the current window has one asset browser, it uses that one.
+- If the current window has multiple asset browsers, it uses the biggest one.
+- Otherwise Blender goes over the other windows (if there are any), and do a
+  similar search. The first window it sees that has an asset browser wins.
+
+.. _poselib-preview-images:
+
+Controlling the Look of Preview Images
+--------------------------------------------
+
+The preview images are rendered with the active Scene camera. This approach was
+preferred over rendering a specific 3D Viewport for two main reasons:
+
+- There is only one scene camera active at any time, making it predictable which
+  camera is used.
+- The camera, as well as the rest of the scene, can be set up specifically for
+  rendering the thumbnails. Pose library files are intended for that purpose: to
+  contain the poses and render their preview images.
+
+The preview images are rendered using the Workbench Engine. Switch the scene to
+use that as render engine, and you’ll see various options to influence the look.
+Select a pose asset and press the Generate Preview button to re-render the
+preview icon with the current settings.
+
+You can also animate settings, such as the background colour, light positions
+and intensities, etc. Use this to your advantage!
+
+Scene Animation for Preview Images
+--------------------------------------------
+
+Sometimes it’s handy to have a few different background colours or camera angles
+for your poses. Many facial poses are made with a specific camera angle in mind.
+
+- Background colour can be animated. In this case just for fun, but for more
+  serious applications this could be used to indicate a certain character, or a
+  mood, or anything else.
+- The active camera can be switched by using camera markers.
+
+Both make it possible to choose a specific frame to pick the background colour
+and camera angle. Pose the character, click the Create Pose Asset button, and
+the pose Action will be keyed on the current frame. This means it’s easy to edit
+the pose and refresh its preview icon, because you know exactly which frame it
+was originally created on.
+
+
+
+Using the Pose Library
+=================================
+
+The Pose Library can be used to pose a character in a few different ways. In
+short, you can fully apply a pose or blend it into the character's current pose
+interactively. How exactly these operations work depends on where you use them.
+This section will explain the use from both the Asset Browser and the 3D
+Viewport.
+
+
+Use from the Asset Browser
+--------------------------------------------
+
+The Pose Library can be used directly from the Asset Browser. The **Pose Library
+panels will appear** when the active object is an Armature and in pose mode. The
+:doc:`catalog system </files/asset_libraries/catalogs>` and the filter bar at
+the top can be used to search for specific poses.
+
+Click the **Apply** button to apply the pose to the character. If there are any

@@ Diff output truncated at 10240 characters. @@
