manual/conf.py

@@ -26,7 +26,7 @@ sys.setrecursionlimit(2000)
 
 # Not used directly by Sphinx, but used by this file and the buildbot.
 
-blender_version = '4.1'
+blender_version = '4.0'
 
 
 # -- Project information -----------------------------------------------------

manual/editors/3dview/display/overlays.rst

@@ -14,16 +14,20 @@ Clicking the icon toggles all overlays in the 3D Viewport.
 The drop-down button displays a popover with more detailed settings,
 which are described below.
 
-The available options depend on the mode that the 3D Viewport is in.
+Next to the Viewport Overlays popover could be a second popover.
+The availability of these options depend on the mode the 3D Viewport is in or what type of object is selected.
+These settings are described later on in this page.
 
 
-Object Mode
-===========
+
+General
+=======
 
 The following options are always present, independent of the current mode.
 Some of the overlays can be customized in the
 :doc:`Viewport Preferences </editors/preferences/viewport>`.
 
+
 Guides
 ------
 
@@ -42,23 +46,23 @@ Subdivision
 Text Info
    Show various bits of information in the top left corner of the viewport.
 
-   View Perspective
-      Name of the :doc:`View Perspective </editors/3dview/navigate/projections>`,
-      such as "Top Orthographic" or "User Perspective."
-   Playback Frame Rate (FPS)
-      Displays the Frames Per Second at which the animation is playing.
-      By default, Blender goes through every single frame, which may result in an FPS that's lower than
-      intended (and the animation playing slower than realtime); the FPS turns red in this case.
-      You can change this behavior in the Playback popover of the :doc:`Timeline </editors/timeline>`.
-   Object Info
-      Shows the current frame in parentheses, followed by the names of the selected
-      :doc:`Collection </scene_layout/collections/index>` and the :ref:`active object <object-active>`.
-      When applicable, also shows the selected :doc:`Shape Key </animation/shape_keys/introduction>`
-      and (in angle brackets) the :doc:`Marker </animation/markers>` on the current frame.
-      If the object has a keyframe on the current frame, the Object Info is displayed in yellow.
-   Grid Resolution
-      When the view is aligned to a world axis (see :doc:`/editors/3dview/navigate/viewpoint`),
-      the Text Info additionally shows the smallest distance between two parallel grid lines.
+   - **View Perspective** --
+     Name of the :doc:`View Perspective </editors/3dview/navigate/projections>`,
+     such as "Top Orthographic" or "User Perspective."
+   - **Playback Frame Rate (FPS)** --
+     Displays the Frames Per Second at which the animation is playing.
+     By default, Blender goes through every single frame, which may result in an FPS that's lower than
+     intended (and the animation playing slower than realtime); the FPS turns red in this case.
+     You can change this behavior in the Playback popover of the :doc:`Timeline </editors/timeline>`.
+   - **Object Info** --
+     Shows the current frame in parentheses, followed by the names of the selected
+     :doc:`Collection </scene_layout/collections/index>` and the :ref:`active object <object-active>`.
+     When applicable, also shows the selected :doc:`Shape Key </animation/shape_keys/introduction>`
+     and (in angle brackets) the :doc:`Marker </animation/markers>` on the current frame.
+     If the object has a keyframe on the current frame, the Object Info is displayed in yellow.
+   - **Grid Resolution** --
+     When the view is aligned to a world axis (see :doc:`/editors/3dview/navigate/viewpoint`),
+     the Text Info additionally shows the smallest distance between two parallel grid lines.
 
 Statistics
    Show information about the amount of objects and geometry.
@@ -66,8 +70,8 @@ Statistics
    For example, selecting a mesh gives info on the number of vertices, edges, and faces,
    while selecting a light shows the number of lights in the scene.
 
-   - Objects -- Number of the selected objects and the total count.
-   - Geometry -- Displays information about the current scene depending on the mode and object type.
+   - **Objects** -- Number of the selected objects and the total count.
+   - **Geometry** -- Displays information about the current scene depending on the mode and object type.
      This can be the number of vertices, faces, triangles, or bones.
 
 HDRI Preview
@@ -160,8 +164,8 @@ Size
 
 .. _3dview-overlay-mesh_edit_mode:
 
-Mesh Edit Mode
-==============
+Mesh Edit Mode Overlays
+=======================
 
 The following options are available when in Mesh Edit Mode.
 
@@ -252,6 +256,7 @@ Face Angle
    The :doc:`Measure </editors/3dview/toolbar/measure>` tool for measuring
    arbitrary distances and angles.
 
+
 .. _mesh-display-normals:
 
 Normals
@@ -292,8 +297,8 @@ Face Marks
    Display Freestyle face marks.
 
 
-Sculpt Mode
-===========
+Sculpt Mode Overlays
+====================
 
 Mask
    Show :ref:`Masks <sculpt-mask-menu>` as overlays on an object. The opacity of the overlay can be adjusted.
@@ -302,8 +307,8 @@ Face Sets
    The opacity of the overlay can be adjusted.
 
 
-Vertex Paint
-============
+Vertex Paint Overlays
+=====================
 
 .. _bpy.types.View3DOverlay.vertex_paint_mode_opacity:
 
@@ -313,8 +318,8 @@ Show Wire
    Display mesh edges in white (unlike the *Wireframe* overlay which shows them in black).
 
 
-Weight Paint
-============
+Weight Paint Overlays
+=====================
 
 Opacity
    The opacity of the overlay.
@@ -322,12 +327,9 @@ Zero Weights
    Display unreferenced and zero-weighted areas in black.
    This helps to identify areas with very low weights that have been painted onto.
 
-   None
-      Vertices are displayed in the usual way.
-   Active
-      Vertices are shown in black if they have no weight in the active vertex group.
-   All
-      Vertices are shown in black if they have no weight in any vertex group.
+   :None: Vertices are displayed in the usual way.
+   :Active: Vertices are shown in black if they have no weight in the active vertex group.
+   :All: Vertices are shown in black if they have no weight in any vertex group.
 
 Show Weight Contours
    Show contour lines formed by points with the same interpolated weight.
@@ -339,8 +341,8 @@ Show Wire
    Display mesh edges in white (unlike the *Wireframe* overlay which shows them in black).
 
 
-Texture Paint
-=============
+Texture Paint Overlays
+======================
 
 .. _bpy.types.View3DOverlay.texture_paint_mode_opacity:
 
@@ -348,8 +350,8 @@ Stencil Mask Opacity
    Opacity of the :doc:`stencil mask </sculpt_paint/texture_paint/tool_settings/mask>` overlay.
 
 
-Bones
-=====
+Pose Mode Overlays
+==================
 
 Fade Geometry
    Show the bones on top and face other geometry to the back.
@@ -360,8 +362,7 @@ Bone Wireframe Opacity
    The maximum opacity used for bones drawn in the *Wireframe*
    :doc:`shading mode </editors/3dview/display/shading>`
    (or in *Solid* shading mode with X-Ray active).
-   This is helpful when it is necessary to reduce clutter and focus on
-   the mesh rather than bones.
+   This is helpful when it is necessary to reduce clutter and focus on the mesh rather than bones.
 
 
 .. _3dview-overlay-grease-pencil:
@@ -369,6 +370,8 @@ Bone Wireframe Opacity
 Grease Pencil
 =============
 
+These overlays are available when a :doc:`/grease_pencil/index` object is selected.
+
 Onion Skin
    Show ghosts of the keyframes before and after the current frame.
    If :doc:`Multiframe </grease_pencil/multiframe>` is enabled,
@@ -387,6 +390,7 @@ Fade Inactive Objects
 
    Fade Grease Pencil Objects
       Include or exclude Grease Pencil objects.
+
 Edit Lines
    Show edit lines in Edit Mode.
 Only in Multiframe

manual/editors/file_browser.rst

@@ -225,12 +225,14 @@ The region is divided into separate panels each containing a :ref:`UI List <ui-l
 Clicking on one of the directories will immediately navigate to that folder.
 
 
-.. _bpy.types.SpaceFileBrowser.system_folders:
+.. _bpy.types.SpaceFileBrowser.bookmarks:
 
-Volumes
-^^^^^^^
+Bookmarks
+^^^^^^^^^
 
-Contains all OS-defined available volumes, e.g. drives or network mounts.
+Contains folders that you want to be able to access often without having to navigate to them in the File Browser.
+To the right of that list are buttons to perform basic management actions on your bookmarks,
+e.g. add/remove an entry, move it up or down in the list, etc.
 
 
 .. _bpy.types.SpaceFileBrowser.system_bookmarks:
@@ -241,14 +243,12 @@ System
 Contains OS-defined common directories, like the main user folder...
 
 
-.. _bpy.types.SpaceFileBrowser.bookmarks:
+.. _bpy.types.SpaceFileBrowser.system_folders:
 
-Bookmarks
-^^^^^^^^^
+Volumes
+^^^^^^^
 
-Contains folders that you want to be able to access often without having to navigate to them in the File Browser.
-To the right of that list are buttons to perform basic management actions on your bookmarks,
-e.g. add/remove an entry, move it up or down in the list, etc.
+Contains all OS-defined available volumes, e.g. drives or network mounts.
 
 
 .. _bpy.types.SpaceFileBrowser.recent_folders:

manual/editors/graph_editor/fcurves/editing.rst

@@ -410,7 +410,7 @@ Blend to Default Value
 
 .. reference::
 
-   :Menu:      :menuselection:`Key --> Blend --> Blend to Neighbor`
+   :Menu:      :menuselection:`Key --> Blend --> Blend to Default Value`
 
 Transitions the current keyframe towards the property's default value.
 To use this operator, drag the mouse left or right to adjust the operator's *Blend* property.
@@ -514,7 +514,7 @@ Direction
 .. _bpy.ops.graph.scale_average:
 
 Scale Average
-=============
+-------------
 
 .. reference::
 
@@ -530,7 +530,7 @@ Factor
 .. _bpy.ops.graph.push_pull:
 
 Push Pull
-=========
+---------
 
 .. reference::
 
@@ -545,7 +545,7 @@ Factor
 .. _bpy.ops.graph.time_offset:
 
 Time Offset
-===========
+-----------
 
 .. reference::
 

manual/modeling/geometry_nodes/introduction.rst

@@ -23,9 +23,8 @@ Geometry nodes can modify different types of geometry:
 * :doc:`Volumes </modeling/volumes/introduction>`
 * :doc:`Instances </modeling/geometry_nodes/instances>`
 
-
 The interface of the modifier is described in the
 :doc:`Modifier </modeling/modifiers/generate/geometry_nodes>` page.
 
 To expand Blender with node-group operators see the description in the
-:doc:`Operators </modeling/geometry_nodes/operators>` page.
+:doc:`/modeling/geometry_nodes/tools` page.

manual/modeling/geometry_nodes/tools.rst

@@ -1,9 +1,9 @@
 .. index:: Geometry Nodes; Tools
 .. _bpy.types.GeometryNode:
 
-################
-Node-based Tools
-################
+****************
+Node-Based Tools
+****************
 
 Geometry Nodes can be used to expand the core functionality of Blender via node group defined tools.
 They can be shared as any regular node group assets.
@@ -13,6 +13,7 @@ They can be shared as any regular node group assets.
 
    Node group tools integrated in the Selection menu.
 
+
 Tool Context
 ============
 
@@ -25,6 +26,7 @@ them as Assets if they want to share them.
 
    The :doc:`Inspection </modeling/geometry_nodes/inspection>` features are not supported on this context: Viewer Node and Socket Inspection.
 
+
 Asset
 =====
 
@@ -36,16 +38,19 @@ The asset options need to be set on the :doc:`Asset Browser </editors/asset_brow
 The catalog is used to determined in which menu the tool is available. Assets that have no catalog assigned to them, or local tools
 are exposed in the Unassigned menu.
 
+
 Tool Settings
 =============
 
 The node group inputs will be exposed as in the :doc:`Adjust Last Operation </interface/undo_redo>` panel.
 
+
 Supported Modes and Data-Types
 ==============================
 
 Tools are only possible for Edit and Sculpting mode, for Mesh and Curve objects.
 
+
 Tool-specific Nodes
 ===================
 
@@ -62,6 +67,7 @@ The following nodes are only supported in the tool context:
    The :doc:`Self Object </modeling/geometry_nodes/input/scene/self_object>` node returns the Active object
    when inside a Tool node group.
 
+
 Non-supported Nodes
 ===================
 

manual/physics/fluid/type/domain/guides.rst

@@ -28,7 +28,7 @@ use guiding in the simulation.
 
 .. _bpy.types.FluidDomainSettings.guide_alpha:
 
-Velocity Factor
+Weight
    Controls the lag of the guiding. A larger value (also known as the 'alpha' guiding value)
    results in a greater lag.
 

manual/render/shader_nodes/shader/glass.rst

@@ -38,9 +38,9 @@ Distribution
    Microfacet distribution to use.
 
    :GGX: GGX microfacet distribution.
-   :Multiscatter GGX: :guilabel:`Cycles Only`
-      GGX with additional correction to account for multiple scattering,
-      preserve energy and prevent unexpected darkening at high roughness.
+   :Multiscatter GGX:
+      Takes multiple scattering events between microfacets into account.
+      This gives more energy conserving results, which would otherwise be visible as excessive darkening.
    :Beckmann: :guilabel:`Cycles Only`
       Beckmann microfacet distribution.
 

manual/render/shader_nodes/shader/glossy.rst

@@ -53,14 +53,12 @@ Properties
 Distribution
    Microfacet distribution to use.
 
+   :GGX: GGX microfacet distribution.
+   :Multiscatter GGX:
+      Takes multiple scattering events between microfacets into account.
+      This gives more energy conserving results, which would otherwise be visible as excessive darkening.
    :Beckmann: :guilabel:`Cycles Only`
       Beckmann microfacet distribution.
-   :GGX: GGX microfacet distribution.
-   :Ashikhmin-Shirley: :guilabel:`Cycles Only`
-      Ashikhmin-Shirley microfacet distribution.
-   :Multiscatter GGX: :guilabel:`Cycles Only`
-      GGX with additional correction to account for multiple scattering,
-      preserve energy and prevent unexpected darkening at high roughness.
 
 
 Outputs

manual/render/shader_nodes/shader/hair_principled.rst

@@ -24,6 +24,9 @@ easy-to-use shader for rendering hair and fur.
 Inputs
 ======
 
+Common
+------
+
 Color
    The RGB color of the strand. Only used in Direct coloring.
 
@@ -103,40 +106,6 @@ Tint
 
 Absorption Coefficient
    Attenuation coefficient :math:`\sigma`.
-Roughness
-   Specify how much the glints are smoothed in the direction of the hair shaft.
-   Too low values will smoothen the hair to the point of looking almost metallic,
-   making glints look like :term:`Fireflies`; while setting it too high will result in a Lambertian look.
-
-   .. figure:: /images/render_shader-nodes_shader_hair-principled_demo-roughness.jpg
-      :align: center
-
-      Roughness.
-
-Radial Roughness
-   Specify how much the glints are smoothed in the direction of the hair normal.
-   Too low values will concentrate the glint;
-   while setting it too high will spread the light across the width of the strand.
-
-   .. hint::
-
-      Mathematically, this parameter is mapped to the logistic distribution's
-      scale factor :math:`s` (section 4.1 of [CBTB16]_).
-
-.. figure:: /images/render_shader-nodes_shader_hair-principled_demo-radial-roughness.jpg
-   :align: center
-
-   Radial Roughness.
-
-Coat
-   Simulate a shiny coat of fur, by reducing the Roughness to the given factor
-   only for the first light bounce (diffuse).
-   Range :math:`[0, 1]` equivalent to a reduction of :math:`[0\%, 100\%]` of the original Roughness.
-
-   .. figure:: /images/render_shader-nodes_shader_hair-principled_demo-coat.jpg
-      :align: center
-
-      Coat.
 
 IOR
    Index of refraction (:term:`IOR`) defining how much the ray changes direction.
@@ -181,6 +150,76 @@ Random
    instanced with the value obtained from :menuselection:`Hair Info --> Random`.
 
 
+Chiang Model
+------------
+
+The Chiang model is based on a Gaussian distribution with separate roughness
+along and orthogonal to the hair.
+
+Roughness
+   Specify how much the glints are smoothed in the direction of the hair shaft.
+   Too low values will smoothen the hair to the point of looking almost metallic,
+   making glints look like :term:`Fireflies`; while setting it too high will result in a Lambertian look.
+
+   .. figure:: /images/render_shader-nodes_shader_hair-principled_demo-roughness.jpg
+      :align: center
+
+      Roughness.
+
+Radial Roughness
+   Specify how much the glints are smoothed in the direction of the hair normal.
+   Too low values will concentrate the glint;
+   while setting it too high will spread the light across the width of the strand.
+
+   .. hint::
+
+      Mathematically, this parameter is mapped to the logistic distribution's
+      scale factor :math:`s` (section 4.1 of [CBTB16]_).
+
+.. figure:: /images/render_shader-nodes_shader_hair-principled_demo-radial-roughness.jpg
+   :align: center
+
+   Radial Roughness.
+
+Coat
+   Simulate a shiny coat of fur, by reducing the Roughness to the given factor
+   only for the first light bounce (diffuse).
+   Range :math:`[0, 1]` equivalent to a reduction of :math:`[0\%, 100\%]` of the original Roughness.
+
+   .. figure:: /images/render_shader-nodes_shader_hair-principled_demo-coat.jpg
+      :align: center
+
+      Coat.
+
+
+Huang Model
+-----------
+
+The Huang model is based on microfacet based reflection and transmission,
+and supports elliptically shaped hair.
+
+Aspect Ratio
+   The ratio of the minor axis to the major axis of an elliptical cross-section.
+   Recommended values are 0.8~1 for Asian hair, 0.65~0.9 for Caucasian hair, 0.5~0.65 for
+   African hair. The major axis is aligned with the curve normal, which can be created
+   with geometry nodes, but is not supported in legacy particle hair.
+
+Roughness
+   Microfacet roughness for reflection and transmission.
+
+Reflection
+   Optional factor for modulating the first light bounce off the hair surface.
+   The color of this component is always white. Keep this 1.0 for physical correctness.
+Transmission
+   Optional factor for modulating the transmission component. Picks up the color of the
+   pigment inside the hair. Keep this 1.0 for physical correctness.
+Secondary Reflection
+   Optional factor for modulating the component which is transmitted into the hair,
+   reflected off the backside of the hair and then transmitted out of the hair. This
+   component is oriented approximately around the incoming direction, and picks up the
+   color of the pigment inside the hair. Keep this 1.0 for physical correctness
+
+ 
 Properties
 ==========
 
@@ -223,8 +262,7 @@ BSDF
 References
 ==========
 
-This shader is an implementation of the paper by Chiang et al. [CBTB16]_,
-which was used in the Disney film, "Zootopia"\ :sup:`®`.
+This shader is an implementation of the papers by Chiang et al. [CBTB16]_ and Huang et al. [HHH22]_.
 
 .. [CBTB16] Chiang, M. J. , Bitterli, B. , Tappan, C. and Burley, B. (2016),
    A Practical and Controllable Hair and Fur Model for Production Path Tracing. Computer Graphics Forum, 35: 275-283.
@@ -233,3 +271,9 @@ which was used in the Disney film, "Zootopia"\ :sup:`®`.
 .. [EFHLA11] d'Eon, E. , Francois, G. , Hill, M. , Letteri, J. and Aubry, J. (2011),
    An Energy‐Conserving Hair Reflectance Model. Computer Graphics Forum, 30: 1181-1187.
    `doi:10.1111/j.1467-8659.2011.01976.x <https://doi.org/10.1111/j.1467-8659.2011.01976.x>`__
+
+.. [HHH22] Huang W., Hullin M.B. Hanika J. (2022)
+   A Microfacet-based Hair Scattering Model. Computer Graphics Forum, 41: 79-91.
+   `doi:10.1111/cgf.14588 <https://doi.org/10.1111/cgf.14588>`__
+
+

manual/render/shader_nodes/shader/principled.rst

@@ -10,39 +10,49 @@ Principled BSDF
 
 The *Principled* :abbr:`BSDF (Bidirectional Scattering Distribution Function)`
 that combines multiple layers into a single easy to use node.
-It is based on the Disney principled model also known as the "PBR" shader,
-making it compatible with other software such as Pixar's Renderman\ :sup:`®`
-and Unreal Engine\ :sup:`®`. Image textures painted or baked from
-software like Substance Painter\ :sup:`®` may be directly linked to
-the corresponding parameters in this shader.
+It can model a wide variety of materials.
 
-This "Uber" shader includes multiple layers to create a wide variety of materials.
-The base layer is a user controlled mix between diffuse, metal,
-subsurface scattering and transmission.
-On top of that there is a specular layer, sheen layer and clearcoat layer.
+It is based on OpenPBR Surface shading model, and provides parameters
+compatible with similar PBR shaders found in other software,
+such as the Disney and Standard Surface models.
+Image textures painted or baked from software like Substance Painter
+may be directly linked to the corresponding parameters in this shader.
 
-.. note::
 
-   The emphasis on compatibility with other software means that it interprets
-   certain input parameters differently from older Blender nodes.
+Layers and Components
+=====================
 
+The base layer is a mix between metal, diffuse, subsurface, and transmission components.
+Most materials will use one of these components, though it is possible to smoothly mix
+between them.
+
+.. figure:: /images/render_shader-nodes_principled_layers.svg
+
+The metal component is opaque and only reflect lights. Diffuse and subsurface components
+have a specular layer. Diffuse is fully opaque, while subsurface also involves light
+scattering just below the surface. Both sit below a specular layer. The transmission
+component includes both specular reflection and refraction.
+
+On top of all base layers there is an optional glossy coat. And finally the sheen layer
+sits on top of all other layers, to add fuzz or dust.
+
+Light emission can also be added. This is below the coat and sheen layers, to model
+for example emissive displays with a coat or dust.
 
 Inputs
 ======
 
 Base Color
-   Diffuse or metal surface color.
+   Overall color of the material used for diffuse, subsurface, metal and transmission.
 Roughness
-   Specifies microfacet roughness of the surface for diffuse and specular reflection.
+   Specifies microfacet roughness of the surface for specular reflection and transmission.
 Metallic
-   Blends between a non-metallic and metallic material model.
+   Blends between a dielectric and metallic material model.
+   At 0.0 the material consists of a diffuse or transmissive base layer, with a specular reflection layer on top.
    A value of 1.0 gives a fully specular reflection tinted with the base color,
    without diffuse reflection or transmission.
-   At 0.0 the material consists of a diffuse or transmissive base layer, with a specular reflection layer on top.
 IOR
-   Index of refraction for transmission.
-Transmission
-   Mix between fully opaque surface at zero and fully glass like transmission at one.
+   Index of refraction for specular reflection and transmission.
 Alpha
    Controls the transparency of the surface, with 1.0 fully opaque.
    Usually linked to the Alpha output of an Image Texture node.
@@ -50,133 +60,148 @@ Normal
    Controls the normals of the base layers.
 
 
-Substance
----------
-
 Subsurface
-   Mix between diffuse and subsurface scattering.
-   Rather than being a simple mix between Diffuse and Subsurface Scattering,
-   it acts as a multiplier for the Subsurface Radius.
-Subsurface Radius
+----------
+
+Subsurface scattering is used to render materials such as skin, milk and wax.
+Light scatters below the surface to create a soft appearance.
+
+Method
+   Rendering method to simulate subsurface scattering.
+
+   :Christensen-Burley:
+      An approximation to physically-based volume scattering.
+      This method is less accurate than *Random Walk* however,
+      in some situations this method will resolve noise faster.
+   :Random Walk: :guilabel:`Cycles Only`
+      Provides accurate results for thin and curved objects.
+      Random Walk uses true volumetric scattering inside the mesh,
+      which means that it works best for closed meshes.
+      Overlapping faces and holes in the mesh can cause problems.
+   :Random Walk (Skin): :guilabel:`Cycles Only`
+      Random walk method optimized for skin rendering, with
+      radius automatically adjusted based on color and subsurface
+      entry direction using mix of diffuse and custom IOR. It
+      tends to retain greater surface detail and color.
+
+Weight
+   Blend between diffuse surface and subsurface scattering.
+   Typically should be zero or one (either fully diffuse or subsurface)
+Radius
    Average distance that light scatters below the surface.
    Higher radius gives a softer appearance, as light bleeds into shadows and through the object.
    The scattering distance is specified separately for the RGB channels,
    to render materials such as skin where red light scatters deeper.
    The X, Y and Z values are mapped to the R, G and B values, respectively.
-Subsurface Color
-   Subsurface scattering base color.
-Subsurface IOR :guilabel:`Cycles Only`
-   Index of refraction for *Subsurface Scattering*.
-Subsurface Anisotropy :guilabel:`Cycles Only`
-   Controls the directionality of subsurface scattering.
+Scale
+  Scale applied to the radius.
+IOR :guilabel:`Cycles Only`
+   Index of refraction used for rays that enter the subsurface component. This may be set to
+   a different value than the global IOR to simulate different layers of skin.
+Anisotropy :guilabel:`Cycles Only`
+   Directionanltiy of volume scattering within the subsurface medium. Zero scatters uniformly
+   in all directories, with higher values scattering more strongly forward.
+   For example skin has been measure to have an anisotropy of 0.8.
 
 
 Specular
 --------
 
-Specular
-   Amount of dielectric specular reflection. Specifies facing (along normal)
-   reflectivity in the most common 0 - 8% range.
-
-   .. hint::
-
-      To compute this value for a realistic material with a known index of
-      refraction, you may use this special case of the Fresnel formula:
-      :math:`specular = ((ior - 1)/(ior + 1))^2 / 0.08`
-
-      For example:
-
-      - water: ior = 1.33, specular = 0.25
-      - glass: ior = 1.5, specular = 0.5
-      - diamond: ior = 2.417, specular = 2.15
-
-      Since materials with reflectivity above 8% do exist, the field allows values above 1.
-
-Specular Tint
-   Tints the facing specular reflection using the base color, while glancing reflection remains white.
-
-   Normal dielectrics have colorless reflection, so this parameter is not technically physically correct
-   and is provided for faking the appearance of materials with complex surface structure.
-Anisotropic :guilabel:`Cycles Only`
-   Amount of anisotropy for specular reflection. Higher values give elongated highlights along the tangent direction;
-   negative values give highlights shaped perpendicular to the tangent direction.
-Anisotropic Rotation :guilabel:`Cycles Only`
-   Rotates the direction of anisotropy, with 1.0 going full circle.
-
-   .. hint::
-
-      Compared to the *Anisotropic BSDF* node, the direction of highlight elongation
-      is rotated by 90°. Add 0.25 to the value to correct.
-
-Tangent
-   Controls the tangent for the *Anisotropic* layer.
-
-
-Coat
-----
-
-Clearcoat
-   Extra white specular layer on top of others.
-   This is useful for materials like car paint and the like.
-Clearcoat Roughness:
-   Roughness of clearcoat specular.
-Clearcoat Normal
-   Controls the normals of the *Clearcoat* layer.
-
-
-Sheen
------
-
-Sheen
-   Amount of soft velvet like reflection near edges, for simulating materials such as cloth.
-Sheen Roughness
-   Controls the amount of color that is reflected back to the camera,
-   higher values reflect more color and can give a dusty appearance, while lower values look fuzzy and darker.
-Sheen Tint
-   The color of the sheen reflection.
-
-
-Emission
---------
-
-Emission
-   Light emission from the surface, like the Emission shader.
-Emission Strength
-   Strength of the emitted light. A value of 1.0 will ensure that the object
-   in the image has the exact same color as the *Emission Color*, i.e. make it 'shadeless'.
-
-
-Properties
-==========
+Controls for both the metallic component and specular layer on top of diffuse and subsurface.
 
 Distribution
    Microfacet distribution to use.
 
    :GGX:
       A method that is faster than *Multiple-scattering GGX* but is less physically accurate.
-   :Multiscatter GGX: :guilabel:`Cycles Only`
-      GGX with additional correction to account for multiple scattering,
-      preserve energy and prevent unexpected darkening at high roughness.
+   :Multiscatter GGX:
+      Takes multiple scattering events between microfacets into account.
+      This gives more energy conserving results,
+      which would otherwise be visible as excessive darkening.
 
-Subsurface Method
-   Rendering method to simulate subsurface scattering.
+IOR Level
+    Adjustment to the IOR to increase or decrease intensity of the specular layer.
+    0.5 means no adjustment, 0 removes all reflections, 1 doubles them at normal incidence.
 
-   .. note:: EEVEE does not support the *Random Walk* methods.
+    This input is designed for conveniently texturing the IOR and amount of specular
+    reflection.
 
-   :Christensen-Burley:
-      An approximation to physically-based volume scattering.
-      This method is less accurate than *Random Walk* however,
-      in some situations this method will resolve noise faster.
-   :Random Walk (Fixed Radius):
-      Provides accurate results for thin and curved objects.
-      Random Walk uses true volumetric scattering inside the mesh,
-      which means that it works best for closed meshes.
-      Overlapping faces and holes in the mesh can cause problems.
-   :Random Walk:
-      Behaves similarly to *Random Walk (Fixed Radius)* but modulates
-      the *Subsurface Radius* based on the *Color*, *Subsurface Anisotropy*, and *Subsurface IOR*.
-      This method thereby attempts to retain greater surface detail and color
-      than *Random Walk (Fixed Radius)*.
+Tint
+   Color tint for specular and metallic reflection.
+
+   For non-metallic tints provides artistic control over the color specular reflections at normal incidence,
+   while grazing reflections remain white. In reality non-metallic specular reflection is fully white.
+
+   For metallic materials tints the edges to simulate complex IOR as found in materials such as gold or copper.
+
+Anisotropic :guilabel:`Cycles Only`
+   Amount of anisotropy for specular reflection. Higher values give elongated highlights along the tangent direction;
+   negative values give highlights shaped perpendicular to the tangent direction.
+Anisotropic Rotation :guilabel:`Cycles Only`
+   Rotates the direction of anisotropy, with 1.0 going full circle.
+
+   Compared to the *Anisotropic BSDF* node, the direction of highlight elongation
+   is rotated by 90°. Add 0.25 to the value to correct.
+
+Tangent
+   Controls the tangent for the *Anisotropic* layer.
+
+
+Transmission
+------------
+
+Transmission is used to render materials like glass and liquids, where the surface both
+reflects light and transmits it into the interior of the object
+
+Weight
+   Mix between fully opaque surface at zero and fully transmissive at one.
+
+Coat
+----
+
+Coat on top of the materials, to simulate for example a clearcoat, lacquer or car paint.
+
+Weight
+   Controls the intensity of the coat layer, both the reflection and the tinting.
+   Typically should be zero or one for physically-based materials, but may be textured
+   to vary the amount of coating across the surface.
+Roughness
+	 Roughness of the coat layer.
+IOR
+   Index of refraction of the coat layer. Affects its reflectivity as well as the falloff of coat tinting.
+Tint
+   Adds a colored tint to the coat layer by modeling absorption in the layer.
+   Saturation increases at shallower angles, as the light travels farther
+   through the medium, depending on the IOR.
+Normal
+   Controls the normals of the *Coat* layer, for example to add a smooth coating on a rough surface.
+
+
+Sheen
+-----
+
+Sheen simulates very small fibers on the surface.
+For cloth this adds a soft velvet like reflection near edges.
+It can also be used to simulate dust on arbitrary materials.
+
+Weight
+   Controls in the intensity of the sheen layer.
+Roughness
+   Roughness of the sheen reflection.
+Tint
+   The color of the sheen reflection.
+
+
+Emission
+--------
+
+Light emission from the surface.
+
+Color
+   Color of light emission from the surface.
+Strength
+   Strength of the emitted light. A value of 1.0 will ensure that the object
+   in the image has the exact same color as the *Emission Color*, i.e. make it 'shadeless'.
 
 
 Outputs
@@ -184,13 +209,3 @@ Outputs
 
 BSDF
    Standard shader output.
-
-
-Examples
-========
-
-Below are some examples of how all the Principled BSDF's parameters interact with each other.
-
-.. figure:: /images/render_shader-nodes_shader_principled_example-1a.jpg
-.. figure:: /images/render_shader-nodes_shader_principled_example-2a.jpg
-.. figure:: /images/render_shader-nodes_shader_principled_example-2b.jpg

manual/render/shader_nodes/shader/refraction.rst

@@ -31,11 +31,8 @@ Properties
 ==========
 
 Distribution
-   Microfacet distribution to use.
-
-   :GGX: GGX microfacet distribution.
-   :Beckmann: :guilabel:`Cycles Only`
-      Beckmann microfacet distribution.
+   Microfacet distribution to use. *Sharp* results in perfectly sharp refractions,
+   while *Beckmann* and *GGX* can use the *Roughness* input for blurry refractions.
 
 
 Outputs

tools_maintenance/generate_node_screenshots.py

@@ -1,6 +1,7 @@
 import bpy
 from dataclasses import dataclass
 from itertools import islice
+from pathlib import Path
 
 
 @dataclass
@@ -92,8 +93,9 @@ class MakeScreenshotsOperator(bpy.types.Operator):
         return {'RUNNING_MODAL'}
 
     def modal(self, context, event):
-        temp_path = f"/home/jacques/Downloads/temp.png"
-        filepath = f"/home/jacques/Downloads/node-types_{self.current_name}.png"
+        base_path = Path.home() / "Downloads" / "node_screenshots"
+        temp_path = str(base_path / "temp.png")
+        filepath = str(base_path / f"node-types_{self.current_name}.png")
         bpy.ops.screen.screenshot_area(filepath=temp_path)
 
         rect = node_region_rect(context.region, self.current_node)

tools_make/make_update.py

@@ -188,7 +188,7 @@ if __name__ == "__main__":
             manual_skip_msg = manual_update(args)
         if manual_skip_msg:
             manual_skip_msg = "Manual repository skipped: " + manual_skip_msg + "\n"
-    if not args.no_locale:
+    if not args.no_locale and os.path.exists(locale_dir):
         locale_skip_msg = git_update_skip(args, locale_dir)
         if not locale_skip_msg:
             locale_skip_msg = locale_update(args)