more api changes and +docs

SharpGLTF.ruleset

@@ -2,6 +2,7 @@
 <RuleSet Name="SharpGLTF" ToolsVersion="15.0">
   <Rules AnalyzerId="StyleCop.Analyzers" RuleNamespace="StyleCop.Analyzers">
     <Rule Id="AD0001" Action="None" />
+    <Rule Id="CS1591" Action="None" />
     <Rule Id="SA1008" Action="None" />
     <Rule Id="SA1009" Action="None" />
     <Rule Id="SA1025" Action="None" />
@@ -21,6 +22,7 @@
     <Rule Id="SA1309" Action="None" />
     <Rule Id="SA1400" Action="None" />
     <Rule Id="SA1402" Action="None" />
+    <Rule Id="SA1405" Action="None" />
     <Rule Id="SA1413" Action="None" />
     <Rule Id="SA1500" Action="None" />
     <Rule Id="SA1501" Action="None" />

src/SharpGLTF.Core/Collections/LinqDictionary.cs

@@ -9,6 +9,9 @@ namespace SharpGLTF.Collections
     /// <summary>
     /// Wraps a standard dictionary, but performs a transform in the value
     /// </summary>
+    /// <typeparam name="TKey">The dictionary key type.</typeparam>
+    /// <typeparam name="TValueIn">The internal value type.</typeparam>
+    /// <typeparam name="TValueOut">The exposed value type.</typeparam>
     struct ReadOnlyLinqDictionary<TKey, TValueIn, TValueOut> : IReadOnlyDictionary<TKey, TValueOut>
     {
         #region lifecycle

src/SharpGLTF.Core/Collections/ReferenceComparer.cs

@@ -9,6 +9,7 @@ namespace SharpGLTF.Collections
     /// this class is used to compare two T class references,
     /// bypassing any equality operator implemented by the T class.
     /// </summary>
+    /// <typeparam name="T">Any ByRef type.</typeparam>
     /// <see href="https://stackoverflow.com/questions/4901320/is-there-any-kind-of-referencecomparer-in-net"/>
     sealed class ReferenceComparer<T> : IEqualityComparer<T>
         where T : class

src/SharpGLTF.Core/Schema2/khr.lights.cs

@@ -103,9 +103,12 @@ namespace SharpGLTF.Schema2
         #region properties
 
         /// <summary>
+        /// Gets the Local light direction.
+        /// </summary>
+        /// <remarks>
         /// For light types that have a direction (directional and spot lights),
         /// the light's direction is defined as the 3-vector (0.0, 0.0, -1.0)
-        /// </summary>
+        /// </remarks>
         public static Vector3 LocalDirection => -Vector3.UnitZ;
 
         /// <summary>

src/SharpGLTF.Core/SharpGLTF.Core.csproj

@@ -24,6 +24,10 @@
     <None Include="..\..\LICENSE" Pack="true" PackagePath="" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="..\Shared\Guard.cs" Link="Debug\Guard.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
       <_Parameter1>SharpGLTF.Tests</_Parameter1>

src/SharpGLTF.Toolkit/Geometry/PackedMeshBuilder.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using System.Linq;
 
 namespace SharpGLTF.Geometry
 {
@@ -8,11 +9,56 @@ namespace SharpGLTF.Geometry
 
     class PackedMeshBuilder<TMaterial>
     {
-        public PackedMeshBuilder(string name) { _MeshName = name; }
+        #region lifecycle
+
+        internal static IEnumerable<PackedMeshBuilder<TMaterial>> PackMeshes<TVertex, TJoints>(IEnumerable<SkinnedMeshBuilder<TMaterial, TVertex, TJoints>> meshBuilders)
+            where TVertex : struct, VertexTypes.IVertex
+            where TJoints : struct, VertexTypes.IJoints
+        {
+            var vertexBlocks = VertexTypes.VertexUtils.CreateVertexMemoryAccessors
+                (
+                meshBuilders
+                .SelectMany(item => item.Primitives)
+                .Select(item => item.Vertices)
+                ).ToList();
+
+            var indexBlocks = VertexTypes.VertexUtils.CreateIndexMemoryAccessors
+                (
+                meshBuilders
+                .SelectMany(item => item.Primitives)
+                .Select(item => item.Indices)
+                ).ToList();
+
+            int idx = 0;
+
+            foreach (var meshBuilder in meshBuilders)
+            {
+                var dstMesh = new PackedMeshBuilder<TMaterial>(meshBuilder.Name);
+
+                foreach (var primitiveBuilder in meshBuilder.Primitives)
+                {
+                    dstMesh.AddPrimitive(primitiveBuilder.Material, vertexBlocks[idx], indexBlocks[idx]);
+
+                    ++idx;
+                }
+
+                yield return dstMesh;
+            }
+        }
+
+        private PackedMeshBuilder(string name) { _MeshName = name; }
+
+        #endregion
+
+        #region data
 
         private readonly string _MeshName;
         private readonly List<PackedPrimitiveBuilder<TMaterial>> _Primitives = new List<PackedPrimitiveBuilder<TMaterial>>();
 
+        #endregion
+
+        #region API
+
         public void AddPrimitive(TMaterial material, Memory.MemoryAccessor[] vrtAccessors, Memory.MemoryAccessor idxAccessor)
         {
             var p = new PackedPrimitiveBuilder<TMaterial>(material, vrtAccessors, idxAccessor);
@@ -30,10 +76,14 @@ namespace SharpGLTF.Geometry
 
             return dstMesh;
         }
+
+        #endregion
     }
 
     class PackedPrimitiveBuilder<TMaterial>
     {
+        #region lifecycle
+
         internal PackedPrimitiveBuilder(TMaterial material, Memory.MemoryAccessor[] vrtAccessors, Memory.MemoryAccessor idxAccessor)
         {
             _Material = material;
@@ -41,10 +91,18 @@ namespace SharpGLTF.Geometry
             _IndexAccessors = idxAccessor;
         }
 
+        #endregion
+
+        #region data
+
         private readonly TMaterial _Material;
         private readonly Memory.MemoryAccessor[] _VertexAccessors;
         private readonly Memory.MemoryAccessor _IndexAccessors;
 
+        #endregion
+
+        #region API
+
         internal void CopyToMesh(Mesh dstMesh, Func<TMaterial, Material> materialEvaluator)
         {
             dstMesh.CreatePrimitive()
@@ -52,5 +110,7 @@ namespace SharpGLTF.Geometry
                         .WithVertexAccessors(_VertexAccessors)
                         .WithIndicesAccessor(PrimitiveType.TRIANGLES, _IndexAccessors);
         }
+
+        #endregion
     }
 }

src/SharpGLTF.Toolkit/Geometry/SkinnedMeshBuilder.cs

@@ -137,40 +137,7 @@ namespace SharpGLTF.Geometry
 
             return new int[0];
         }
-
-        internal static IEnumerable<PackedMeshBuilder<TMaterial>> PackMeshes(IEnumerable<SkinnedMeshBuilder<TMaterial, TVertex, TJoints>> meshBuilders)
-        {
-            var vertexBlocks = VertexTypes.VertexUtils.CreateVertexMemoryAccessors
-                (
-                meshBuilders
-                .SelectMany(item => item.Primitives)
-                .Select(item => item.Vertices)
-                ).ToList();
-
-            var indexBlocks = VertexTypes.VertexUtils.CreateIndexMemoryAccessors
-                (
-                meshBuilders
-                .SelectMany(item => item.Primitives)
-                .Select(item => item.Indices)
-                ).ToList();
-
-            int idx = 0;
-
-            foreach (var meshBuilder in meshBuilders)
-            {
-                var dstMesh = new PackedMeshBuilder<TMaterial>(meshBuilder.Name);
-
-                foreach (var primitiveBuilder in meshBuilder.Primitives)
-                {
-                    dstMesh.AddPrimitive(primitiveBuilder.Material, vertexBlocks[idx], indexBlocks[idx]);
-
-                    ++idx;
-                }
-
-                yield return dstMesh;
-            }
-        }
-
+        
         #endregion
     }
 }

src/SharpGLTF.Toolkit/Geometry/VertexTypes/VertexUtils.cs

@@ -10,15 +10,15 @@ namespace SharpGLTF.Geometry.VertexTypes
 
     public static class VertexUtils
     {
-        public static IEnumerable<MemoryAccessor[]> CreateVertexMemoryAccessors<TVertex, TSkin>(this IEnumerable<IReadOnlyList<(TVertex, TSkin)>> vertexBlocks)
+        public static IEnumerable<MemoryAccessor[]> CreateVertexMemoryAccessors<TVertex, TJoints>(this IEnumerable<IReadOnlyList<(TVertex, TJoints)>> vertexBlocks)
             where TVertex : struct, IVertex
-            where TSkin : struct, IJoints
+            where TJoints : struct, IJoints
         {
             // total number of vertices
             var totalCount = vertexBlocks.Sum(item => item.Count);
 
             // vertex attributes
-            var attributes = GetVertexAttributes(typeof(TVertex), typeof(TSkin), totalCount);
+            var attributes = GetVertexAttributes(typeof(TVertex), typeof(TJoints), totalCount);
 
             // create master vertex buffer
             int byteStride = attributes[0].ByteStride;
@@ -39,7 +39,7 @@ namespace SharpGLTF.Geometry.VertexTypes
                     var finfo = GetVertexField(typeof(TVertex), accessor.Attribute.Name);
                     if (finfo == null)
                     {
-                        finfo = GetVertexField(typeof(TSkin), accessor.Attribute.Name);
+                        finfo = GetVertexField(typeof(TJoints), accessor.Attribute.Name);
                         isSkin = true;
                     }
 
@@ -94,7 +94,7 @@ namespace SharpGLTF.Geometry.VertexTypes
             return null;
         }
 
-        private static MemoryAccessInfo[] GetVertexAttributes(Type vertexType, Type skinType, int itemsCount)
+        private static MemoryAccessInfo[] GetVertexAttributes(Type vertexType, Type jointsType, int itemsCount)
         {
             var attributes = new List<MemoryAccessInfo>();
 
@@ -104,7 +104,7 @@ namespace SharpGLTF.Geometry.VertexTypes
                 if (attribute.HasValue) attributes.Add(attribute.Value);
             }
 
-            foreach (var finfo in skinType.GetFields())
+            foreach (var finfo in jointsType.GetFields())
             {
                 var attribute = _GetMemoryAccessInfo(finfo);
                 if (attribute.HasValue) attributes.Add(attribute.Value);
@@ -139,7 +139,7 @@ namespace SharpGLTF.Geometry.VertexTypes
             return new MemoryAccessInfo(attribute.Name, 0, 0, 0, dimensions.Value, attribute.Encoding, attribute.Normalized);
         }
 
-        internal static Single[] GetScalarColumn<TVertex, TSkin>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TSkin)> vertices, bool vertexOrSkin)
+        internal static Single[] GetScalarColumn<TVertex, TJoints>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TJoints)> vertices, bool vertexOrSkin)
         {
             var dst = new Single[vertices.Count];
 
@@ -153,7 +153,7 @@ namespace SharpGLTF.Geometry.VertexTypes
             return dst;
         }
 
-        internal static Vector2[] GetVector2Column<TVertex, TSkin>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TSkin)> vertices, bool vertexOrSkin)
+        internal static Vector2[] GetVector2Column<TVertex, TJoints>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TJoints)> vertices, bool vertexOrSkin)
         {
             var dst = new Vector2[vertices.Count];
 
@@ -167,7 +167,7 @@ namespace SharpGLTF.Geometry.VertexTypes
             return dst;
         }
 
-        internal static Vector3[] GetVector3Column<TVertex, TSkin>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TSkin)> vertices, bool vertexOrSkin)
+        internal static Vector3[] GetVector3Column<TVertex, TJoints>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TJoints)> vertices, bool vertexOrSkin)
         {
             var dst = new Vector3[vertices.Count];
 
@@ -181,7 +181,7 @@ namespace SharpGLTF.Geometry.VertexTypes
             return dst;
         }
 
-        internal static Vector4[] GetVector4Column<TVertex, TSkin>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TSkin)> vertices, bool vertexOrSkin)
+        internal static Vector4[] GetVector4Column<TVertex, TJoints>(this System.Reflection.FieldInfo finfo, IReadOnlyList<(TVertex, TJoints)> vertices, bool vertexOrSkin)
         {
             var dst = new Vector4[vertices.Count];
 

src/SharpGLTF.Toolkit/Schema2/MeshExtensions.cs

@@ -45,7 +45,7 @@ namespace SharpGLTF.Schema2
                 .ToDictionary(k => k, k => materialEvaluator(k));
 
             // creates meshes and primitives using MemoryAccessors using a single, shared vertex and index buffer
-            var srcMeshes = Geometry.SkinnedMeshBuilder<TMaterial, TVertex, TJoints>
+            var srcMeshes = Geometry.PackedMeshBuilder<TMaterial>
                 .PackMeshes(meshBuilders)
                 .ToList();
 
@@ -172,9 +172,9 @@ namespace SharpGLTF.Schema2
             return primitive.WithVertexAccessors(xvertices);
         }
 
-        public static MeshPrimitive WithVertexAccessors<TVertex, TSkin>(this MeshPrimitive primitive, IReadOnlyList<(TVertex, TSkin)> vertices)
+        public static MeshPrimitive WithVertexAccessors<TVertex, TJoints>(this MeshPrimitive primitive, IReadOnlyList<(TVertex, TJoints)> vertices)
             where TVertex : struct, Geometry.VertexTypes.IVertex
-            where TSkin : struct, Geometry.VertexTypes.IJoints
+            where TJoints : struct, Geometry.VertexTypes.IJoints
         {
             var memAccessors = Geometry.VertexTypes.VertexUtils.CreateVertexMemoryAccessors(new[] { vertices }).First();
 

src/SharpGLTF.Toolkit/SharpGLTF.Toolkit.csproj

@@ -52,7 +52,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Compile Include="..\SharpGLTF\Debug\Guard.cs" Link="Debug\Guard.cs" />
+    <Compile Include="..\Shared\Guard.cs" Link="Debug\Guard.cs" />
   </ItemGroup>
 
   <ItemGroup>