From fd739d2d72f9a325d464394c0a8195cf82c7efcc Mon Sep 17 00:00:00 2001 From: sean Date: Mon, 26 Feb 2024 21:22:59 +0100 Subject: [PATCH] Add: More examples for tools & link other projects --- .gitignore | 8 +++++--- README.md | 10 +++++++++ docs/api.rst | 3 +-- docs/overview.rst | 12 +++++++++++ docs/tools.rst | 35 +++++++++++++++++++++++++++++++- examples/gl_viewer/gl_viewer.cpp | 3 --- 6 files changed, 62 insertions(+), 9 deletions(-) diff --git a/.gitignore b/.gitignore index e4d0d9817..08156c8bd 100644 --- a/.gitignore +++ b/.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/ diff --git a/README.md b/README.md index 7156d6e60..e056a9801 100644 --- a/README.md +++ b/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. diff --git a/docs/api.rst b/docs/api.rst index ef6fff71e..4c7a3f81a 100644 --- a/docs/api.rst +++ b/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: diff --git a/docs/overview.rst b/docs/overview.rst index e16c0660e..946d35693 100644 --- a/docs/overview.rst +++ b/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 `_: The examples of this modern OpenGL 4.6 abstraction make use of fastgltf. +- `wad2gltf `_: A WAD to glTF converter +- `Castor3D `_: A multi-OS 3D engine + .. _accessor-tools: diff --git a/docs/tools.rst b/docs/tools.rst index 75f517889..34987507f 100644 --- a/docs/tools.rst +++ b/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(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( + asset, positionAccessor, [&](glm::vec3 pos, std::size_t idx) { + vertices[idx].position = pos; + vertices[idx].uv = glm::vec2(); + }); diff --git a/examples/gl_viewer/gl_viewer.cpp b/examples/gl_viewer/gl_viewer.cpp index 809e2b661..2e15ba2b9 100644 --- a/examples/gl_viewer/gl_viewer.cpp +++ b/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 positions(positionAccessor.count); - fastgltf::copyFromAccessor(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);