[Bf-docboard-svn] bf-manual: [7266] trunk/blender_docs/manual: Addons: Update glTF documentation for 2.91

Ed Mackey noreply at blender.org
Thu Oct 22 02:53:58 CEST 2020 

Revision: 7266
          https://developer.blender.org/rBM7266
Author:   emackey
Date:     2020-10-22 02:53:58 +0200 (Thu, 22 Oct 2020)
Log Message:
-----------
Addons: Update glTF documentation for 2.91

Reviewed on GitHub: https://github.com/KhronosGroup/glTF-Blender-IO/pull/1239

Modified Paths:
--------------
    trunk/blender_docs/manual/addons/import_export/scene_gltf2.rst

Added Paths:
-----------
    trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png
    trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png

Modified: trunk/blender_docs/manual/addons/import_export/scene_gltf2.rst
===================================================================
--- trunk/blender_docs/manual/addons/import_export/scene_gltf2.rst	2020-10-21 20:50:45 UTC (rev 7265)
+++ trunk/blender_docs/manual/addons/import_export/scene_gltf2.rst	2020-10-22 00:53:58 UTC (rev 7266)
@@ -26,11 +26,13 @@
 - Textures
 - Cameras
 - Punctual lights (point, spot, and directional)
+- Extensions (listed below)
+- Extras (custom properties)
 - Animation (keyframe, shape key, and skinning)
 
 
 Meshes
-------
+======
 
 glTF's internal structure mimics the memory buffers commonly used by graphics chips
 when rendering in real-time, such that assets can be delivered to desktop, web, or mobile clients
@@ -43,7 +45,7 @@
 
 
 Materials
----------
+=========
 
 The core material system in glTF supports a metal/rough :abbr:`PBR (Physically Based Rendering)` workflow
 with the following channels of information:
@@ -52,11 +54,15 @@
 - Metallic
 - Roughness
 - Baked Ambient Occlusion
-- Normal Map
+- Normal Map (Tangent-space, +Y up)
 - Emissive
-- Clearcoat (requires ``KHR_materials_clearcoat``)
-- Transmission (requires ``KHR_materials_transmission``)
 
+Some additional material properties or types of materials can be expressed using glTF extensions:
+
+- Clearcoat, Clearcoat Roughness, Clearcoat Normal (uses ``KHR_materials_clearcoat``)
+- Transmission (uses ``KHR_materials_transmission``)
+- "Shadeless" materials (uses ``KHR_materials_unlit``)
+
 .. figure:: /images/addons_import-export_scene-gltf2_material-channels.jpg
 
    An example of the various image maps available in the glTF 2.0 core format. This is
@@ -91,11 +97,7 @@
    When image textures are used by materials, glTF requires that images be in PNG or JPEG format.
    The add-on will automatically convert images from other formats, increasing export time.
 
-.. tip::
 
-   To create Shadeless (Unlit) materials, use the Background material type.
-
-
 Base Color
 ^^^^^^^^^^
 
@@ -230,6 +232,68 @@
    the Principled BSDF node directly.
 
 
+Clearcoat
+^^^^^^^^^
+
+When the Clearcoat input on the Principled BSDF node has a non-zero default value or
+Image Texture node connected, the ``KHR_materials_clearcoat`` glTF extension will be
+included in the export. This extension will also include a value or Image Texture
+from the Clearcoat Roughness input if available.
+
+If Image Textures are used, glTF requires that the clearcoat values be written to
+the red (``R``) channel, and clearcoat roughness to the green (``G``) channel.
+If monochrome images are connected, the addon will remap them to these color channels
+during export.
+
+The Clearcoat Normal input accepts the same kinds of inputs as the base Normal input,
+specifically a tangent-space normal map with +Y up, and a user-defined strength.
+This input can re-use the same normal map that the base material is using, or can
+be assigned its own normal map, or can be left disconnected for a smooth coating.
+
+All clearcoat-related Image Texture node(s) should have their *Color Space* set to Non-Color.
+
+.. figure:: /images/addons_import-export_scene-gltf2_material-clearcoat.png
+
+   An example of a complex clearcoat application that will export correctly to glTF.
+   A much simpler, smooth coating could be applied from just the Principled BSDF node alone.
+
+
+Transmission
+^^^^^^^^^^^^
+
+When the Transmission input on the Principled BSDF node has a non-zero default value or
+Image Texture node connected, the ``KHR_materials_transmission`` glTF extension will be
+included in the export. When a texture is used, glTF stores the values in
+the red (``R``) channel. The *Color Space* should be set to Non-Color.
+
+Transmission is different from alpha blending, because transmission allows full-strength
+specular reflections. In glTF, alpha blending is intended to represent physical materials
+that are partially missing from the specified geometry, such as medical gauze wrap. Transmission
+is intended to represent physical materials that are solid but allow non-specularly-reflected
+light to transmit through the material, like glass.
+
+glTF does not offer a separate "Transmission Roughness," but the material's base roughness
+can be used to blur the transmission, like frosted glass.
+
+.. tip::
+
+   Typically the alpha blend mode of a transmissive material should remain "Opaque," the
+   default setting, unless the material only partially covers the specified geometry.
+
+.. note::
+
+   In real-time engines where transmission is supported, various technical limitations
+   in the engine may determine which parts of the scene are visible through the
+   transmissive surface. In particular, transmissive materials may not be visible behind
+   other transmissive materials. These limitations affect physically-based transmission,
+   but not alpha-blended non-transmissive materials.
+
+.. warning::
+
+   Transmission is complex for real-time rendering engines to implement, and support
+   for the ``KHR_materials_transmission`` glTF extension is not yet widespread.
+
+
 Double-Sided / Backface Culling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -318,8 +382,19 @@
    A Principled BSDF material with an emissive texture.
 
 
+Exporting a Shadeless (Unlit) Material
+--------------------------------------
+
+To export an unlit material, mix in a camera ray, and avoid using the Principled BSDF node.
+
+.. figure:: /images/addons_import-export_scene-gltf2_material-unlit.png
+
+   One of several similar node arrangements that will export
+   ``KHR_materials_unlit`` and render shadeless in Blender.
+
+
 Extensions
-----------
+==========
 
 The core glTF 2.0 format can be extended with extra information, using glTF extensions.
 This allows the file format to hold details that were not considered universal at the time of first publication.
@@ -350,8 +425,29 @@
 - ``KHR_texture_transform``
 
 
+Third-party glTF Extensions
+---------------------------
+
+It is possible for Python developers to add Blender support for additional glTF extensions
+by writing their own third-party add-on, without modifying this glTF add-on. For more information,
+`see the example on GitHub <https://github.com/KhronosGroup/glTF-Blender-IO/tree/master/example-addons/example_gltf_extension>`__
+and if needed,
+`register an extension prefix <https://github.com/KhronosGroup/glTF/blob/master/extensions/Prefixes.md>`__.
+
+
+Custom Properties
+=================
+
+Custom properties are always imported, and will be exported from most objects if the
+:menuselection:`Include --> Custom Properties` option is selected before export. These
+are stored in the ``extras`` field on the corresponding object in the glTF file.
+
+Unlike glTF extensions, custom properties (extras) have no defined name-space, and may
+be used for any user-specific or application-specific purposes.
+
+
 Animation
----------
+=========
 
 glTF allows multiple animations per file, with animations targeted to
 particular objects at time of export. To ensure that an animation is included,
@@ -391,13 +487,6 @@
    they must be on a mesh object which is a direct child of the bones' armature.
 
 
-Custom Properties
------------------
-
-Custom properties on most objects are preserved in glTF export/import, and
-may be used for user-specific purposes.
-
-
 File Format Variations
 ======================
 

Added: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png
===================================================================
(Binary files differ)

Index: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png
===================================================================
--- trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png	2020-10-21 20:50:45 UTC (rev 7265)
+++ trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png	2020-10-22 00:53:58 UTC (rev 7266)

Property changes on: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-clearcoat.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/octet-stream
\ No newline at end of property
Added: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png
===================================================================
(Binary files differ)

Index: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png
===================================================================
--- trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png	2020-10-21 20:50:45 UTC (rev 7265)
+++ trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png	2020-10-22 00:53:58 UTC (rev 7266)

Property changes on: trunk/blender_docs/manual/images/addons_import-export_scene-gltf2_material-unlit.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/octet-stream
\ No newline at end of property

More information about the Bf-docboard-svn mailing list