docs/index.rst
.. libgltf documentation master file, created by
sphinx-quickstart on Mon Oct 12 18:56:34 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to libgltf's documentation!
===================================
|glTF 2.0| |docs| |bestpractices| |visit-milstones|
|github-action| |coveralls|
|codacy| |lgtm-alerts| |lgtm-grade|
This project was generated by glTF 2.0 JSON schema and support to load the glTF 2.0 file to a struct `SGlTF`.
It was used in glTFForUE4_.
Features
==========
* `glTF 2.0`_
* Load the gltf/embedded/glb file
* This is a static library
* Cross platform
* C++17
* Supports the Unicode and UTF8
* Supports some extensions
* `KHR_draco_mesh_compression` - `Google's Draco`_
* `KHR_lights_punctual`
* `KHR_materials_clearcoat`
* `KHR_materials_emissive_strength`
* `KHR_materials_ior`
* `KHR_materials_iridescence`
* `KHR_materials_sheen`
* `KHR_materials_specular`
* `KHR_materials_transmission`
* `KHR_materials_unlit`
* `KHR_materials_variants`
* `KHR_materials_volume`
* `KHR_texture_transform`
* `ADOBE_materials_thin_transparency`
* `AGI_articulations`
* `AGI_stk_metadata`
* `CESIUM_primitive_outline`
* `EXT_lights_ies`
* `EXT_mesh_gpu_instancing`
* `EXT_texture_webp`
* `FB_geometry_metadata`
* `MSFT_lod`
* `MSFT_texture_dds`
* Platforms
* Windows
* Win32 (win32)
* x64 (win64)
* Linux (linux)
* macOS (macos)
* Android
* armeabi-v7a
* armeabi-v7a-with-neon
* arm64-v8a
* x86
* x86_64
* iOS
* iOS (iphoneos)
* watchOS (watchos)
* simulator
Getting Started
===============
#. Update the submodule
Run :code:`git submodule update --init`
#. Generate the project by [CMake]
Run :code:`cmake -G "[GENERATOR BY YOUR SYSTEM]" [LIBGLTF FOLDER]`
#. Build the project and generate the static library :code:`libgltf.(lib/a)`
#. Include :code:`libgltf/libgltf.h` in your project.
#. Link the static library :code:`libgltf.(lib/a)` in your project.
You have to link the static library `draco.lib` or `draco.a` with your project, if you want to support the `Google's Draco`_.
And you can find the draco in the external folder.
Code example:
.. code-block:: cpp
std::shared_ptr<libgltf::IglTFLoader> gltf_loader = libgltf::IglTFLoader::Create(/*a function to load the file by std::istream*/);
gltf_loader->Execute();
std::shared_ptr<libgltf::SGlTF> loaded_gltf = gltf_loader->glTF().lock();
if (!loaded_gltf)
{
printf("failed to load your gltf file");
}
Usage
==========
Generate the *makefile* or *ninja* or *visual c++ project* or *xcode project* by CMake_.
It is a static library - :code:`libgltf.(lib/a)`.
How to use
^^^^^^^^^^
Load the glTF file
------------------
You can load the glTF file by the function - :code:`libgltf::IglTFLoader::Create`, like this:
.. code-block:: cpp
std::shared_ptr<libgltf::IglTFLoader> gltf_loader = libgltf::IglTFLoader::Create(
[](const std::string& _path)
{
std::filesystem::path file_path;
if (_path.empty())
file_path = std::filesystem::path("Monster.gltf");
else
file_path = std::filesystem::path("Monster.gltf").parent_path().append(_path);
std::shared_ptr<std::istream> stream_ptr = nullptr;
if (!std::filesystem::exists(file_path))
return stream_ptr;
stream_ptr = std::make_shared<std::ifstream>(file_path.string(), std::ios::in | std::ios::binary);
return stream_ptr;
});
std::shared_ptr<libgltf::SGlTF> loaded_gltf = gltf_loader->glTF().lock();
if (!loaded_gltf)
{
// the glTF file is valid
return false;
}
Load the mesh data
------------------
And get the mesh data, like this:
.. code-block:: cpp
// get all indices of the triangle
libgltf::TVertexList<1, size_t> triangle_data;
std::shared_ptr<libgltf::TAccessorStream<libgltf::TVertexList<1, size_t> > > triangle_stream = std::make_shared<libgltf::TAccessorStream<libgltf::TVertexList<1, size_t> > >(triangle_data);
gltf_loader->LoadMeshPrimitiveIndicesData(0, 0, triangle_stream);
// get all points of the triangle
libgltf::TVertexList<3, float> position_data;
std::shared_ptr<libgltf::TAccessorStream<libgltf::TVertexList<3, float> > > position_stream = std::make_shared<libgltf::TAccessorStream<libgltf::TVertexList<3, float> > >(position_data);
gltf_loader->LoadMeshPrimitiveAttributeData(0, 0, L"position", position_stream);
Load the image data
-------------------
You can get the image (data and type) by `libgltf::IglTFLoader::LoadImageData`, like this:
.. code-block:: cpp
std::vector<uint8_t> image0_data;
libgltf::string_t image0_data_type;
gltf_loader->LoadImageData(0, image0_data, image0_data_type);
Advance
^^^^^^^^^^
Regenerate new code by the glTF schema
--------------------------------------
Generate the c++11 code:
* You can update the c++11 source code by :code:`jsonschematoc11`.
* You need update and pull the submodule :code:`external/glTF`
#. Run :code:`update_parser_by_scheme.bat`
* For Windows: :code:`cd tools\batch\ && update_parser_by_scheme.bat && cd ..\..\ `
* For Linux/MacOS :code:`cd tools/batch/ && ./update_parser_by_scheme.sh && cd ../../`
#. Build your version by CMake_.
Supports Google's draco
-----------------------
You can update Google's draco submodule in external/draco or pull the draco repo by yourself.
Check the :code:`LIBGLTF_WITH_GOOGLE_DRACO` or set :code:`LIBGLTF_WITH_GOOGLE_DRACO` is `TRUE`.
* Set the :code:`GOOGLE_DRACO_PATH_INCLUDE`, :code:`GOOGLE_DRACO_PATH_BUILD`, :code:`GOOGLE_DRACO_LIBRARY_DRACO_DEBUG`.
* And compile with the submodule - *external/draco*.
Download libraries
------------------
This project is compiled by GitHub action, and you can download the compiled library with `Google's Draco`_ from `the action page`_ or `the release page`_.
In `the action page`_ or `the release page`_, libraries was compiled with `MultiThreading` (/MT or /MTd) for **windows**.
Donation
==============================================================
**Please consider donating to sustain my activities**
|support-buy-a-cup-of-coffee| |donation-beome-a-patreon|
License
==========
`The MIT license`_.
.. _`glTF 2.0`: https://www.khronos.org/gltf/
.. _glTFForUE4: https://github.com/code4game/glTFForUE4
.. _`Google's Draco`: https://github.com/google/draco
.. _CMake: https://cmake.org/
.. _Ninja: https://ninja-build.org
.. _VisualStudio: https://visualstudio.microsoft.com
.. _`the action page`: https://github.com/code4game/libgltf/actions
.. _`the release page`: https://github.com/code4game/libgltf/releases
.. _`The MIT license`: https://github.com/code4game/libgltf/LICENSE
.. |glTF 2.0| image:: https://img.shields.io/badge/glTF-2%2E0-green.svg?style=flat
:target: https://github.com/KhronosGroup/glTF
.. |docs| image:: https://readthedocs.org/projects/libgltf/badge/?version=latest
:target: http://libgltf.rtfd.io/
.. |bestpractices| image:: https://bestpractices.coreinfrastructure.org/projects/1434/badge
:target: https://bestpractices.coreinfrastructure.org/projects/1434
.. |visit-milstones| image:: https://img.shields.io/badge/visit-milestones-blue.svg?style=flat
:target: https://github.com/code4game/libgltf/milestones
.. |github-action| image:: https://github.com/code4game/libgltf/workflows/build/badge.svg
:target: https://github.com/code4game/libgltf/actions?query=workflow%3Abuild
.. |coveralls| image:: https://coveralls.io/repos/github/code4game/libgltf/badge.svg
:target: https://coveralls.io/github/code4game/libgltf
.. |codacy| image:: https://api.codacy.com/project/badge/Grade/fa7ee9a5bc9b4befb703298ca721bc9a
:target: https://www.codacy.com/app/code4game/libgltf?utm_source=github.com&utm_medium=referral&utm_content=code4game/libgltf&utm_campaign=Badge_Grade
.. |lgtm-alerts| image:: https://img.shields.io/lgtm/alerts/g/code4game/libgltf.svg?logo=lgtm&logoWidth=18
:target: https://lgtm.com/projects/g/code4game/libgltf/alerts/
.. |lgtm-grade| image:: https://img.shields.io/lgtm/grade/python/g/code4game/libgltf.svg?logo=lgtm&logoWidth=18
:target: https://lgtm.com/projects/g/code4game/libgltf/context:python
.. |support-buy-a-cup-of-coffee| image:: https://img.shields.io/badge/support-buy%20a%20cup%20of%20coffee-orange.svg?style=flat
:target: https://c4gio.itch.io/libgltf-ue4
.. |donation-beome-a-patreon| image:: https://img.shields.io/badge/donation-become%20a%20patreon-orange.svg?style=flat
:target: https://www.patreon.com/bePatron?u=7553208