+docs

src/SharpGLTF.Core/Memory/README.md

@@ -27,4 +27,4 @@ But the actual encoding and decoding, can be achieved using these wrappers found
 - `MultiArray`
 - `SparseArray`
 
-You can use any of these structures to wrap any byte array and expose it as the given type.
+You can use any of these helper structs to wrap any byte array and expose it as the given type.

src/SharpGLTF.Core/README.md

@@ -3,26 +3,42 @@
 
 #### Namespaces
 
-##### Namespace Schema2
+##### .Animations
+
+Contains classes to help decode and interpolate animation curves.
+
+##### .IO
+
+Code related to JSon serialization.
+
+##### .Schema2
 
 This namespace contains the collection of classes, structures and enumerations that
-represent the bulk of the API to access directly to glTF2 documents.
+represent the bulk of the low level API to access glTF2 documents.
 
 It also contains the main entry point Object that represents a glTF2 model: `ModelRoot`
 
-[Documentation](Schema2/README.md)
 
-##### Namespace IO
+[Additional info](Schema2/README.md)
+
+##### .Memory
+
+glTF2 stores structured arrays as encoded byte buffers that are not easy to read directly.
+
+To facilitate buffered array IO, the __.Memory__ namespace provides a number of helper
+classes and structures that let accessing the data seamlessly.
+
+[Additional info](Memory/README.md)
 
-This namespace contains the helper classes to support JSon serialization.
+##### .Transforms
 
-##### Namespace Memory
+A glTF model usually consist of a scene graph of nodes connected as a visual tree.
+The relationship between nodes is defined with transforms, usually with 4x4 matrices.
 
-glTF2 stores array structures as encoded byte buffers that are not easy to handle directly.
+It also handles the way a mesh is brought from its local space to world space, including skinning and morphing.
 
-[Documentation](Memory/README.md)
 
-#### Extensions
+#### Extensions support
 
 - [x] [KHR_materials_pbrSpecularGlossiness](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_pbrSpecularGlossiness)
 - [x] [KHR_materials_unlit](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit)

src/SharpGLTF.Core/Schema2/README.md

@@ -1,12 +1,12 @@
-# Schema2 namespace
+# SharpGLTF.Schema2
 
 This namespace contains the collection of classes, structures and enumerations that
-represent the bulk of the API to access directly to glTF2 documents.
+represent the bulk of the API to access directly to glTF v2 documents.
 
-Part of the code has been generated directly from the glTF2 schema using
+Part of the code has been generated directly from the glTF v2 schema using
 [SharpGLTF.CodeGen tool](../../build/SharpGLTF.CodeGen).
 
-Not all the objects of glTF2 are exposed directly in the public API, some remain private and
+Not all the objects of glTF v2 are exposed directly in the public API, some remain private and
 can be accessed indirectly with helper classes, for example, materials use this approach.
 
 The main object that represent a glTF document in memory is `ModelRoot`. Internally, it stores
@@ -14,20 +14,21 @@ almost all the model elements in plain lists, and cross referencing is done by i
 The public API implentation tries to simplify document access by resolving the references and
 offering a more C# friendly API.
 
-There's two ways of traverse a glTF document: you can directly access every individual element
+There's two ways to traverse a glTF document; you can directly access every individual element
 using the `ModelRoot.Logical*` collections, which gives you direct access to almost all
-the individual building blocks of the document.
+the individual building blocks as they where originally stored in the document.
 
-But if you want to traverse the document as a visual graph, you start with `ModelRoot.DefaultScene`
-and from there you navigate throught the different properties and collections.
+But if you want to traverse the document as a visual tree graph, you start with `ModelRoot.DefaultScene`
+and from there you navigate throught the different nodes and properties using the `.Visual*` properties.
 
 `ModelRoot` also contains the methods to create, load and save a glTF document:
 
 Creating a new glTF document:
 ```c#
-var model = ModelRoot.CreateModel();
-var scene = model.UseScene("Default Scene");
-var node = scene.CreateNode("Node1");
+var model = SharpGLTF.Schema2.ModelRoot.CreateModel();
+var root = model.UseScene(0).CreateNode("root node");
+root.CreateNode("child node");
+model.SaveGLB("model.glb");
 ```
 
 Loading a glTF document:
@@ -41,7 +42,9 @@ var model = Schema2.ModelRoot.Load("model.gltf");
 model.SaveGLB("model.glb");
 ```
 
-Notice that GLB format has a huge restriction over glTF format, which is the requirement
-to have just one binary buffer file. SharpGLTF detects this case, and if the glTF model
-has multiple buffers, under the hood it clones the whole document, and adjusts the internal
-buffers so there's always one buffer.
+Editing existing glTF models has very limited support, because glTF models are not
+designed to be edited. In particular, removing elements is essentially impossible
+because in many cases data can be shared between elements and would require expensive
+internal data reshuffle.
+
+For glTF edition purposes, refer to [__SharpGLTF.Toolkit__](../../SharpGLTF.Toolkit/README.md)

src/SharpGLTF.Core/Schema2/gltf.Images.cs

@@ -104,9 +104,9 @@ namespace SharpGLTF.Schema2
         #region API
 
         /// <summary>
-        /// Retrieves the image file as a block of bytes.
+        /// Retrieves the image file as a segment of bytes.
         /// </summary>
-        /// <returns>A <see cref="BYTES"/> block containing the image file.</returns>
+        /// <returns>A <see cref="BYTES"/> segment containing the image file, which can be a PNG, JPG, DDS or WEBP format.</returns>
         public BYTES GetImageContent()
         {
             // the image is stored locally in a temporary buffer

src/SharpGLTF.Toolkit/README.md

@@ -2,30 +2,24 @@
 
 #### Overview
 
-SharpGLTF.Toolkit is a collection of classes and utilities aimed to help
+__SharpGLTF.Toolkit__ is a collection of classes and utilities aimed to help
 the developer in creating and editing glTF files in the easiest way possible.
 
 Althought the Schema2 namespace API does support some editing capabilities, in
 practice it stands for the word _"The JPEG of 3D"_ , which essentially means
-that its internal structure is not designed to be easily editable.
-
-so, although you can build glTF scenes directly with the Schema2 namespace API,
-doing so is not trivial, and you will need to do a lot of trickery on your own,
-specially for complex scenes and optimizing assets.
+that its internal structure is not designed to be easily editable. In general,
+the Schema2 API can be considered as "_append only_" with very limited modification
+capabilities.
 
 So the Toolkit API comes to cover the gap, and make things a bit easier to
 create glTF assets programatically.
 
-A lof ot the classes in the toolkit follow the `StringBuilder` API paradigm, which
-is, you start from scratch and you keep adding elements to it until you finish.
-
-
 #### Toolkit Namespaces
 
-- [MeshBuilder.](Geometry/readme.md)
-  - [Vertex formats.](Geometry/VertexTypes/readme.md)
-- [MaterialBuilder.](Materials/readme.md)
-- [SceneBuilder](Scenes/readme.md)
+- [.Scenes](Scenes/readme.md)
+- [.Geometry](Geometry/readme.md)
+  - [.VertexTypes](Geometry/VertexTypes/readme.md)
+- [.Materials](Materials/readme.md)
 
 #### Roadmap