Add: More examples for tools & link other projects

.gitignore

@@ -9,9 +9,10 @@ vcpkg_installed/*
 cmake-build-*/
 
 # IDE specific folders
-.idea/*
-.vscode/*
-.vs/*
+.idea/
+.vscode/
+.vs/
+.cache/
 
 # Binary files
 *.exe
@@ -47,3 +48,4 @@ SpirvTemp/
 docs/xml/
 docs/Doxyfile
 docs/conf.py
+docs/.venv/

README.md

@@ -18,6 +18,16 @@ including accessor tools, the ability to directly write to mapped GPU buffers, a
 
 To learn more about fastgltf, its features, performance and API you can read [the docs](https://fastgltf.readthedocs.io/v0.6.x/).
 
+## Examples and real-world usage
+
+You can find some examples in the `examples/` directory of this repository on how to use fastgltf in a 3D renderer to load glTF files.
+Additionally, this is a list of some interesting projects using fastgltf:
+
+- [Fwog](https://github.com/JuanDiegoMontoya/Fwog): The examples of this modern OpenGL 4.6 abstraction make use of fastgltf.
+- [wad2gltf](https://github.com/DethRaid/wad2gltf): A WAD to glTF converter
+- [Castor3D](https://github.com/DragonJoker/Castor3D): A multi-OS 3D engine
+
+
 ## License
 
 The **fastgltf** library is licensed under the MIT License.

docs/api.rst

@@ -162,6 +162,7 @@ Extensions
 
 .. doxygenfunction:: fastgltf::stringifyExtension
 
+.. doxygenfunction:: fastgltf::stringifyExtensionBits
 
 Category
 --------
@@ -219,8 +220,6 @@ Parser
 Exporter
 --------
 
-.. doxygenfunction:: fastgltf::stringifyExtensionBits
-
 .. doxygenclass:: fastgltf::Exporter
    :members:
    :undoc-members:

docs/overview.rst

@@ -160,6 +160,18 @@ All the nodes, meshes, buffers, textures, ... can now be accessed through the ``
 References in between objects are done with a single ``size_t``,
 which is used to index into the various vectors in the asset.
 
+.. _examples:
+
+Examples and real-world usage
+=============================
+
+You can find some examples in the `examples/` directory of this repository on how to use fastgltf in a 3D renderer to load glTF files.
+Additionally, this is a list of some interesting projects using fastgltf:
+
+- `Fwog <https://github.com/JuanDiegoMontoya/Fwog>`_: The examples of this modern OpenGL 4.6 abstraction make use of fastgltf.
+- `wad2gltf <https://github.com/DethRaid/wad2gltf>`_: A WAD to glTF converter
+- `Castor3D <https://github.com/DragonJoker/Castor3D>`_: A multi-OS 3D engine
+
 
 .. _accessor-tools:
 

docs/tools.rst

@@ -79,7 +79,7 @@ This function essentially does a ``memcpy`` on the contents of the accessor data
 In cases where the `ElementType` is default-constructible, and the accessor type allows direct copying, this performs a direct ``memcpy``.
 Otherwise, this function properly respects normalization and sparse accessors while copying and converting the data.
 
-.. doxygenfunction:: copyFromAccessor(const Asset &asset, const Accessor &accessor, void *dest, const BufferDataAdapter &adapter = {}) -> void
+.. doxygenfunction:: copyFromAccessor(const Asset &asset, const Accessor &accessor, void *dest, const BufferDataAdapter &adapter) -> void
 
 
 Accessor iterators
@@ -125,3 +125,36 @@ As this is a functional interface it is possible to also use lambdas for this:
    fastgltf::copyFromAccessor(asset.get(), accessor, accessorData.data(), [&](const fastgltf::Buffer& buffer) const {
        return fileBytes.data();
    });
+
+
+Example: Loading primitive positions
+====================================
+
+The following snippet illustrates how one could potentially load vertex positions for a primitive into a OpenGL buffer using the accessor tools.
+
+.. code:: c++
+
+   fastgltf::Primitive* primitive = ...;
+
+   // findAttribute returns a iterator into the underlying vector of primitive attributes.
+   // Note that the glTF spec requires every primitive to have a POSITION,
+   // so it's perfectly valid to assert that positionIt is never nullptr.
+   auto* positionIt = primitive->findAttribute("POSITION");
+   auto& positionAccessor = asset.accessors[positionIt->second];
+   if (!positionAccessor.bufferViewIndex.has_value())
+      continue;
+
+   // Create the vertex buffer for this primitive,
+   // and use the accessor tools to copy directly into the mapped buffer.
+   glCreateBuffers(1, &primitive.vertexBuffer);
+   glNamedBufferData(primitive.vertexBuffer,
+                     positionAccessor.count * sizeof(Vertex), nullptr, GL_STATIC_DRAW);
+   auto* vertices = static_cast<Vertex*>(glMapNamedBuffer(primitive.vertexBuffer, GL_WRITE_ONLY));
+
+   // Iterates over the accessor (potentially handling any sparse accessors),
+   // and gives each vertex UV a default value, which need to be loaded separately.
+   fastgltf::iterateAccessorWithIndex<glm::vec3>(
+         asset, positionAccessor, [&](glm::vec3 pos, std::size_t idx) {
+      vertices[idx].position = pos;
+      vertices[idx].uv = glm::vec2();
+   });

examples/gl_viewer/gl_viewer.cpp

@@ -414,9 +414,6 @@ bool loadMesh(Viewer* viewer, fastgltf::Mesh& mesh) {
             if (!positionAccessor.bufferViewIndex.has_value())
                 continue;
 
-			std::vector<glm::vec3> positions(positionAccessor.count);
-			fastgltf::copyFromAccessor<glm::vec3>(asset, positionAccessor, positions.data());
-
 			// Create the vertex buffer for this primitive, and use the accessor tools to copy directly into the mapped buffer.
 			glCreateBuffers(1, &primitive.vertexBuffer);
 			glNamedBufferData(primitive.vertexBuffer, positionAccessor.count * sizeof(Vertex), nullptr, GL_STATIC_DRAW);