Merge tag 'release/6.0.0' into openupm

Release 6.0.0

.yamato/project.metafile

@@ -13,8 +13,6 @@ test_editors:
     version: 2021.3.15f1
   - name: 2020.3
     version: 2020.3.42f1
-  - name: 2019.4
-    version: 2019.4.40f1
 
 upm_test_platforms:
   - name: win

CHANGELOG.md

@@ -4,13 +4,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.0] - 2023-10-04
+
+### Added
+- Custom Extension API (`GLTFast.Extensions` namespace)
+- Support for alternative JSON parsing via Newtonsoft JSON
+- `Accessor.ElementByteSize`: Byte size of one element of that accessor
+- `Accessor.ByteSize`: Overall byte size
+- `IGltfReadable.GetAccessor`: Generic byte-array view into an accessor
+- `GameObjectInstantiator` events that allow further instantiation customizations
+  - `NodeCreated`
+  - `MeshAdded`
+  - `EndSceneCompleted`
+- Value array JSON parsing tests
+- String/enum conversions tests
+- (Import) Clearcoat material support in HDRP and URP (via [KHR_materials_clearcoat](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_clearcoat/) extension)
+- (Export) Clearcoat material export support for HDRP Lit shader
+
+### Changed
+- Renamed `GltfAnimation` to `Animation` for consistent naming.
+- Bumped Burst dependency version to 1.8.4
+- Bumped Mathematics dependency version to 1.3.1
+
+### Fixed
+- Added Obsolete attribute to public schema class fields that are for serialization only and should not get modified directly.
+- More robust parsing of (invalid) enum values
+
 ## [5.2.0] - 2023-09-14
 
 ### Added
 - Runtime tests
 - (Export) Setting for deterministic export (limits concurrency to ensure consistent output)
 - (DOTS) Support for [Entities 1.0][Entities1.0]
-
 ### Changed
 - Optimized `Accessor.GetAccessorAttributeType`
 - Optimized `GltfEntityAsset.ClearScenes` via Burst

Documentation~/ProjectSetup.md

@@ -26,6 +26,7 @@ Depending on the Unity version and render pipeline in use, different shader grap
   - Universal render pipe 12 or newer
   - High-Definition render pipe 10 or newer
   - Built-in render pipe (experimental opt-in; see below)
+- Shader graphs in folder `Runtime/Shader/HDRP` for HDRP-specific material types
 - Shader graphs in folder `Runtime/Shader/Legacy` for older Universal / High-Definition render pipe versions
 - Shaders in folder `Runtime/Shader/Built-In` for the built-in render pipeline
 

Documentation~/config.json

@@ -1,3 +1,3 @@
 {
-    "DefineConstants": "DRACO_UNITY;KTX_UNITY;KTX_UNITY_1_3_OR_NEWER;KTX_UNITY_2_2_OR_NEWER;USING_URP;USING_HDRP;USING_HDRP_10_OR_NEWER;UNITY_PHYSICS;UNITY_IMAGECONVERSION;UNITY_WEBREQUEST_TEXTURE;UNITY_JOBS;MESHOPT;USING_URP_12_OR_NEWER;UNITY_SHADER_GRAPH_12_OR_NEWER;UNITY_ANIMATION;UNITY_DOTS_HYBRID"
+    "DefineConstants": "DRACO_UNITY;KTX_UNITY;KTX_UNITY_1_3_OR_NEWER;KTX_UNITY_2_2_OR_NEWER;USING_URP;USING_HDRP;USING_HDRP_10_OR_NEWER;UNITY_PHYSICS;UNITY_IMAGECONVERSION;UNITY_WEBREQUEST_TEXTURE;UNITY_JOBS;MESHOPT;USING_URP_12_OR_NEWER;UNITY_SHADER_GRAPH_12_OR_NEWER;UNITY_ANIMATION;UNITY_ENTITIES_GRAPHICS;NEWTONSOFT_JSON"
 }

Documentation~/features.md

@@ -103,7 +103,7 @@ The glTF 2.0 specification is fully supported, with only a few minor remarks.
 | KHR_mesh_quantization | ✅ |
 | KHR_texture_basisu | ✅ |
 | KHR_lights_punctual | ✅ | ✅
-| KHR_materials_clearcoat | [ℹ️][ClearCoat] |
+| KHR_materials_clearcoat | ✅ | ✅
 | KHR_materials_sheen | [ℹ️][Sheen] |
 | KHR_materials_transmission | [ℹ️][Transmission] |
 | KHR_materials_variants | [ℹ️][Variants] |
@@ -155,9 +155,9 @@ Not investigated yet:
 | Vertex colors                 | ✅  | ✅   | ✅       |
 | Multiple UV sets              | ✅<sup>2</sup>  | ✅<sup>2</sup>   | ✅<sup>2</sup>       |
 | Texture Transform             | ✅  | ✅   | ✅       |
-| Clear coat                    | [ℹ️][ClearCoat] | [ℹ️][ClearCoat] | [⛔️][ClearCoat] |
+| Clear coat                    | ☑️<sup>3</sup>  | ✅  | [⛔️][ClearCoat] |
 | Sheen                         | [ℹ️][Sheen] | [ℹ️][Sheen] | [⛔️][Sheen] |
-| Transmission                  | [☑️][Transmission]<sup>3</sup> | [☑️][Transmission]<sup>4</sup> | [☑️][Transmission]<sup>4</sup> |
+| Transmission                  | [☑️][Transmission]<sup>4</sup> | [☑️][Transmission]<sup>5</sup> | [☑️][Transmission]<sup>5</sup> |
 | Variants                      | [ℹ️][Variants] | [ℹ️][Variants] | [ℹ️][Variants] |
 | IOR                           | [ℹ️][IOR]      | [ℹ️][IOR]      | [⛔️][IOR]      |
 | Specular                      | [ℹ️][Specular] | [ℹ️][Specular] | [⛔️][Specular] |
@@ -168,9 +168,11 @@ Not investigated yet:
 
 <sup>2</sup>: Two sets of texture coordinates (as required by the glTF 2.0 specification) are supported, but not three or more ([issue][UVSets])
 
-<sup>3</sup>: There are two approximation implementations for transmission in Universal render pipeline. If the Opaque Texture is enabled (in the Universal RP Asset settings), it is sampled to provide proper transmissive filtering. The downside of this approach is transparent objects are not rendered on top of each other. If the opaque texture is not available, the common approximation (see <sup>4</sup> below) is used.
+<sup>3</sup>: Only supports Universal Render Pipeline versions >= 12.0; Only coat mask and smoothness are supported, other coat related properties, such as coat normal, are not supported
 
-<sup>4</sup>: Transmission in Built-In and HD render pipeline does not support transmission textures and is only 100% correct in certain cases like clear glass (100% transmission, white base color). Otherwise it's an approximation.
+<sup>4</sup>: There are two approximation implementations for transmission in Universal render pipeline. If the Opaque Texture is enabled (in the Universal RP Asset settings), it is sampled to provide proper transmissive filtering. The downside of this approach is transparent objects are not rendered on top of each other. If the opaque texture is not available, the common approximation (see <sup>4</sup> below) is used.
+
+<sup>5</sup>: Transmission in Built-In and HD render pipeline does not support transmission textures and is only 100% correct in certain cases like clear glass (100% transmission, white base color). Otherwise it's an approximation.
 
 ### Material Export
 
@@ -198,7 +200,7 @@ Other shaders might (partially) work if they have similar properties (with ident
 | Vertex colors                 | `?` | `?` | `?` |
 | Multiple UV sets              | `?` | `?` | `?` |
 | Texture Transform             | ✅ | ✅ | ✅ |
-| Clear coat                    |  |  | `n/a` |
+| Clear coat                    | `n/a` | ✅ | `n/a` |
 | Sheen                         | `?` | `?` | `n/a` |
 | Transmission                  |  |  | `n/a` |
 | Variants                      |  |  |  |

Runtime/Scripts/AnimationMethod.cs

@@ -15,11 +15,11 @@ public enum AnimationMethod
         /// </summary>
         None,
         /// <summary>
-        /// <see href="https://docs.unity3d.com/Manual/Animations.html">Legacy Animation System</see>
+        /// <a href="https://docs.unity3d.com/Manual/Animations.html">Legacy Animation System</a>
         /// </summary>
         Legacy,
         /// <summary>
-        /// <see href="https://docs.unity3d.com/Manual/AnimationOverview.html">Default Animation System (Mecanim)</see>
+        /// <a href="https://docs.unity3d.com/Manual/AnimationOverview.html">Default Animation System (Mecanim)</a>
         /// </summary>
         Mecanim
     }

Runtime/Scripts/DOTS/EntityInstantiator.cs

@@ -183,8 +183,7 @@ public void SetNodeName(uint nodeIndex, string name) {
         public virtual void AddPrimitive(
             uint nodeIndex,
             string meshName,
-            Mesh mesh,
-            int[] materialIndices,
+            MeshResult meshResult,
             uint[] joints = null,
             uint? rootJoint = null,
             float[] morphTargetWeights = null,
@@ -210,12 +209,22 @@ public virtual void AddPrimitive(
             }
 
 #if UNITY_DOTS_HYBRID
-            var hasMorphTargets = mesh.blendShapeCount > 0;
+            var hasMorphTargets = meshResult.mesh.blendShapeCount > 0;
 
-            for (var index = 0; index < materialIndices.Length; index++) {
-                var material = m_Gltf.GetMaterial(materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
+            for (var index = 0; index < meshResult.materialIndices.Length; index++) {
+                var material = m_Gltf.GetMaterial(meshResult.materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
+
+                RenderMeshUtility.AddComponents(
+                    node,
+                    m_EntityManager,
+                    new RenderMeshDescription(
+                        meshResult.mesh,
+                        material,
+                        layer:m_Settings.Layer,
+                        subMeshIndex:index
+                        )
+                    );
 
-                RenderMeshUtility.AddComponents(node,m_EntityManager,new RenderMeshDescription(mesh,material,layer:m_Settings.Layer,subMeshIndex:index));
                  if(joints!=null || hasMorphTargets) {
                      if (joints != null) {
                          var bones = new Entity[joints.Length];
@@ -235,10 +244,10 @@ public virtual void AddPrimitive(
                  }
             }
 #else
-            var materials = new Material[materialIndices.Length];
-            for (var index = 0; index < materialIndices.Length; index++)
+            var materials = new Material[meshResult.materialIndices.Length];
+            for (var index = 0; index < meshResult.materialIndices.Length; index++)
             {
-                materials[index] = m_Gltf.GetMaterial(materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
+                materials[index] = m_Gltf.GetMaterial(meshResult.materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
             }
 
             var filterSettings = RenderFilterSettings.Default;
@@ -252,9 +261,9 @@ public virtual void AddPrimitive(
                 LightProbeUsage = LightProbeUsage.Off,
             };
 
-            var renderMeshArray = new RenderMeshArray(materials, new[] { mesh });
+            var renderMeshArray = new RenderMeshArray(materials, new[] { meshResult.mesh });
 
-            for (var index = 0; index < materialIndices.Length; index++)
+            for (var index = 0; index < meshResult.materialIndices.Length; index++)
             {
                 RenderMeshUtility.AddComponents(
                     node,
@@ -268,7 +277,7 @@ public virtual void AddPrimitive(
                         )
                     );
 
-                m_EntityManager.SetComponentData(node, new RenderBounds {Value = mesh.bounds.ToAABB()} );
+                m_EntityManager.SetComponentData(node, new RenderBounds {Value = meshResult.mesh.bounds.ToAABB()} );
             }
 
 #endif
@@ -279,8 +288,7 @@ public virtual void AddPrimitive(
         public void AddPrimitiveInstanced(
             uint nodeIndex,
             string meshName,
-            Mesh mesh,
-            int[] materialIndices,
+            MeshResult meshResult,
             uint instanceCount,
             NativeArray<Vector3>? positions,
             NativeArray<Quaternion>? rotations,
@@ -292,10 +300,14 @@ public void AddPrimitiveInstanced(
             }
             Profiler.BeginSample("AddPrimitiveInstanced");
 #if UNITY_DOTS_HYBRID
-            foreach (var materialIndex in materialIndices) {
+            foreach (var materialIndex in meshResult.materialIndices) {
                 var material = m_Gltf.GetMaterial(materialIndex) ?? m_Gltf.GetDefaultMaterial();
                 material.enableInstancing = true;
-                var renderMeshDescription = new RenderMeshDescription(mesh, material, subMeshIndex:materialIndex);
+                var renderMeshDescription = new RenderMeshDescription(
+                    meshResult.mesh,
+                    material,
+                    subMeshIndex:materialIndex
+                    );
                 var prototype = m_EntityManager.CreateEntity(m_NodeArchetype);
                 RenderMeshUtility.AddComponents(prototype,m_EntityManager,renderMeshDescription);
                 if (scales.HasValue) {
@@ -313,10 +325,10 @@ public void AddPrimitiveInstanced(
             }
 #else
 
-            var materials = new Material[materialIndices.Length];
-            for (var index = 0; index < materialIndices.Length; index++)
+            var materials = new Material[meshResult.materialIndices.Length];
+            for (var index = 0; index < meshResult.materialIndices.Length; index++)
             {
-                materials[index] = m_Gltf.GetMaterial(materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
+                materials[index] = m_Gltf.GetMaterial(meshResult.materialIndices[index]) ?? m_Gltf.GetDefaultMaterial();
                 materials[index].enableInstancing = true;
             }
 
@@ -331,8 +343,8 @@ public void AddPrimitiveInstanced(
                 LightProbeUsage = LightProbeUsage.Off,
             };
 
-            var renderMeshArray = new RenderMeshArray(materials, new[] { mesh });
-            for (var index = 0; index < materialIndices.Length; index++)
+            var renderMeshArray = new RenderMeshArray(materials, new[] { meshResult.mesh });
+            for (var index = 0; index < meshResult.materialIndices.Length; index++)
             {
                 var prototype = m_EntityManager.CreateEntity(m_NodeArchetype);
                 m_EntityManager.SetEnabled(prototype, true);

Runtime/Scripts/DontDestroyOnLoad.cs

@@ -8,8 +8,9 @@ namespace GLTFast
 {
 
     /// <summary>
-    /// Makes GameObject survive scene changes (<seealso cref="DontDestroyOnLoad"/>)
+    /// Makes GameObject survive scene changes
     /// </summary>
+    /// <seealso cref="UnityEngine.Object.DontDestroyOnLoad"/>
     public class DontDestroyOnLoad : MonoBehaviour
     {
         void Awake()

Runtime/Scripts/Export/Constants.cs

@@ -7,7 +7,7 @@ namespace GLTFast.Export
 {
     static class Constants
     {
-        public const string version = "5.2.0";
+        public const string version = "6.0.0";
 
         internal const string mimeTypePNG = "image/png";
         internal const string mimeTypeJPG = "image/jpeg";

Runtime/Scripts/Export/GameObjectExport.cs

@@ -29,10 +29,9 @@ public class GameObjectExport
         /// <param name="exportSettings">Export settings</param>
         /// <param name="gameObjectExportSettings">GameObject export settings</param>
         /// <param name="materialExport">Provides material conversion</param>
-        /// <param name="deferAgent">Defer agent; decides when/if to preempt
-        /// export to preserve a stable frame rate <seealso cref="IDeferAgent"/></param>
-        /// <param name="logger">Interface for logging (error) messages
-        /// <seealso cref="ConsoleLogger"/></param>
+        /// <param name="deferAgent">Defer agent (&lt;see cref="IDeferAgent"/&gt;); decides when/if to preempt
+        /// export to preserve a stable frame rate.</param>
+        /// <param name="logger">Interface for logging (error) messages.</param>
         public GameObjectExport(
             ExportSettings exportSettings = null,
             GameObjectExportSettings gameObjectExportSettings = null,
@@ -50,7 +49,7 @@ public GameObjectExport(
         /// Adds a scene to the glTF.
         /// If the conversion to glTF was not flawless (i.e. parts of the scene
         /// were not converted 100% correctly) you still might be able to
-        /// export a glTF. You may use the <seealso cref="CollectingLogger"/>
+        /// export a glTF. You may use the <see cref="CollectingLogger"/>
         /// to analyze what exactly went wrong.
         /// </summary>
         /// <param name="gameObjects">Root level GameObjects (will get added recursively)</param>

Runtime/Scripts/Export/GltfWriter.cs

@@ -117,10 +117,9 @@ struct AttributeData
         /// Provides glTF export independent of workflow (GameObjects/Entities)
         /// </summary>
         /// <param name="exportSettings">Export settings</param>
-        /// <param name="deferAgent">Defer agent; decides when/if to preempt
-        /// export to preserve a stable frame rate <seealso cref="IDeferAgent"/></param>
-        /// <param name="logger">Interface for logging (error) messages
-        /// <seealso cref="ConsoleLogger"/></param>
+        /// <param name="deferAgent">Defer agent (<see cref="IDeferAgent"/>); decides when/if to preempt
+        /// export to preserve a stable frame rate.</param>
+        /// <param name="logger">Interface for logging (error) messages.</param>
         public GltfWriter(
             ExportSettings exportSettings = null,
             IDeferAgent deferAgent = null,
@@ -390,7 +389,7 @@ public void AddLightToNode(int nodeId, int lightId)
                 node = AddChildNode(nodeId, rotation: quaternion.RotateY(math.PI), name: $"{node.name}_Orientation");
             }
             node.extensions = node.extensions ?? new NodeExtensions();
-            node.extensions.KHR_lights_punctual = new NodeLightsPunctual
+            node.Extensions.KHR_lights_punctual = new NodeLightsPunctual
             {
                 light = lightId
             };
@@ -741,10 +740,10 @@ void LogSummary(long jsonLength, long bufferLength)
             var sb = new StringBuilder("glTF summary: ");
             sb.AppendFormat("{0} bytes JSON + {1} bytes buffer", jsonLength, bufferLength);
             if (m_Gltf != null) {
-                sb.AppendFormat(", {0} nodes", m_Gltf.nodes?.Length ?? 0);
+                sb.AppendFormat(", {0} nodes", m_Gltf.Nodes?.Count ?? 0);
                 sb.AppendFormat(" ,{0} meshes", m_Gltf.meshes?.Length ?? 0);
-                sb.AppendFormat(" ,{0} materials", m_Gltf.materials?.Length ?? 0);
-                sb.AppendFormat(" ,{0} images", m_Gltf.images?.Length ?? 0);
+                sb.AppendFormat(" ,{0} materials", m_Gltf.Materials?.Count ?? 0);
+                sb.AppendFormat(" ,{0} images", m_Gltf.Images?.Count ?? 0);
             }
             m_Logger?.Info(sb.ToString());
 #endif
@@ -794,7 +793,7 @@ async Task<bool> Bake(string bufferPath, string directory)
             if (m_Lights != null && m_Lights.Count > 0)
             {
                 RegisterExtensionUsage(Extension.LightsPunctual);
-                m_Gltf.extensions = m_Gltf.extensions ?? new Schema.RootExtension();
+                m_Gltf.extensions = m_Gltf.extensions ?? new Schema.RootExtensions();
                 m_Gltf.extensions.KHR_lights_punctual = m_Gltf.extensions.KHR_lights_punctual ?? new LightsPunctual();
                 m_Gltf.extensions.KHR_lights_punctual.lights = m_Lights.ToArray();
             }