From d040ccec324f97875f75abbf519892e3486efb3f Mon Sep 17 00:00:00 2001 From: Par Winzell Date: Sun, 7 Apr 2019 22:12:31 -0700 Subject: [PATCH] Some README improvements. (More needed...) --- README.md | 124 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 78 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 14992c5..db7e2db 100644 --- a/README.md +++ b/README.md @@ -28,47 +28,64 @@ Or perhaps, as part of a more complex pipeline: You can always run the binary with --help to see what options it takes: ``` -FBX2glTF 2.0: Generate a glTF 2.0 representation of an FBX model. -Usage: - FBX2glTF [OPTION...] [] +FBX2glTF 0.9.6: Generate a glTF 2.0 representation of an FBX model. +Usage: FBX2glTF [OPTIONS] [FBX Model] - -i, --input arg The FBX model to convert. - -o, --output arg Where to generate the output, without suffix. - -e, --embed Inline buffers as data:// URIs within - generated non-binary glTF. - -b, --binary Output a single binary format .glb file. - -d, --draco Apply Draco mesh compression to geometries. - --flip-u Flip all U texture coordinates. - --flip-v Flip all V texture coordinates (default - behaviour!) - --no-flip-v Suppress the default flipping of V texture - coordinates - --pbr-metallic-roughness Try to glean glTF 2.0 native PBR attributes - from the FBX. - --khr-materials-unlit Use KHR_materials_unlit extension to specify - Unlit shader. - --blend-shape-normals Include blend shape normals, if reported - present by the FBX SDK. - --blend-shape-tangents Include blend shape tangents, if reported - present by the FBX SDK. - --long-indices arg Whether to use 32-bit indices - (never|auto|always). - --compute-normals arg When to compute normals for vertices - (never|broken|missing|always). - -k, --keep-attribute arg Used repeatedly to build a limiting set of - vertex attributes to keep. - -v, --verbose Enable verbose output. - -h, --help Show this help. - -V, --version Display the current program version. +Positionals: + FBX Model FILE The FBX model to convert. + +Options: + -h,--help Print this help message and exit + -v,--verbose Include blend shape tangents, if reported present by the FBX SDK. + -V,--version + -i,--input FILE The FBX model to convert. + -o,--output TEXT Where to generate the output, without suffix. + -e,--embed Inline buffers as data:// URIs within generated non-binary glTF. + -b,--binary Output a single binary format .glb file. + --long-indices (never|auto|always) + Whether to use 32-bit indices. + --compute-normals (never|broken|missing|always) + When to compute vertex normals from mesh geometry. + --flip-u Flip all U texture coordinates. + --no-flip-u Don't flip U texture coordinates. + --flip-v Flip all V texture coordinates. + --no-flip-v Don't flip V texture coordinates. + --no-khr-lights-punctual Don't use KHR_lights_punctual extension to export FBX lights. + --user-properties Transcribe FBX User Properties into glTF node and material 'extras'. + --blend-shape-normals Include blend shape normals, if reported present by the FBX SDK. + --blend-shape-tangents Include blend shape tangents, if reported present by the FBX SDK. + -k,--keep-attribute (position|normal|tangent|binormial|color|uv0|uv1|auto) ... + Used repeatedly to build a limiting set of vertex attributes to keep. + + +Materials: + --pbr-metallic-roughness Try to glean glTF 2.0 native PBR attributes from the FBX. + --khr-materials-unlit Use KHR_materials_unlit extension to request an unlit shader. + + +Draco: + -d,--draco Apply Draco mesh compression to geometries. + --draco-compression-level INT in [0 - 10]=7 + The compression level to tune Draco to. + --draco-bits-for-position INT in [1 - 32]=14 + How many bits to quantize position to. + --draco-bits-for-uv INT in [1 - 32]=10 + How many bits to quantize UV coordinates to. + --draco-bits-for-normals INT in [1 - 32]=10 + How many bits to quantize nornals to. + --draco-bits-for-colors INT in [1 - 32]=8 + How many bits to quantize colors to. + --draco-bits-for-other INT in [1 - 32]=8 + How many bits to quantize all other vertex attributes to. ``` Some of these switches are not obvious: - `--embed` is the way to get a single distributable file without using the - binary format. It encodes the binary buffer(s) as a single enormous - base64-encoded `data://` URI. This is a very slow and space-consuming way to - accomplish what the binary format was invented to do simply and efficiently, - but it can be useful e.g. for loaders that don't understand the .glb format. + binary format. It encodes the binary buffer(s) as a single base64-encoded + `data://` URI. This is a very slow and space-consuming way to accomplish what + the binary format was invented to do simply and efficiently, but it can be + useful e.g. for loaders that don't understand the .glb format. - `--flip-u` and `--flip-v`, when enabled, will apply a `x -> (1.0 - x)` function to all `u` or `v` texture coordinates respectively. The `u` version is perhaps not commonly used, but flipping `v` is **the default behaviour**. @@ -104,15 +121,20 @@ Some of these switches are not obvious: ## Building it on your own -This build process has been tested on Linux, Mac OS X and Windows. It requires -CMake 3.5+ and a reasonably C++11 compliant toolchain. +Building FBX2glTF has become slightly more ornery because we now require a full +C++17 toolchain including std::filesystem implementation. + +For now, this means Visual Studio 2019 for Windows, and GCC 8.* the Unix based +systems. We could likely support Clang again, too, but there were complications +on Mac OS X; pull requests welcome. We currently depend on the open source projects [Draco](https://github.com/google/draco), [MathFu](https://github.com/google/mathfu), [Json](https://github.com/nlohmann/json), [cppcodec](https://github.com/tplgy/cppcodec), -[cxxopts](https://github.com/jarro2783/cxxopts), +[CLI11](https://github.com/CLIUtils/CLI11), +[stb](https://github.com/nothings/stb), and [fmt](https://github.com/fmtlib/fmt); all of which are automatically downloaded, configured and built. @@ -120,18 +142,31 @@ You must manually download and install the [Autodesk FBX SDK](https://www.autodesk.com/products/fbx/overview) and accept its license agreement. -**At present, only version 2018.1.1 of the FBX SDK is supported**. The +**At present, only version 2019.2 of the FBX SDK is supported**. The build system will not successfully locate any other version. ### Linux and MacOS X -Compilation on Unix machines should be as simple as: +Compilation on Unix machines might look like: ``` > cd - > cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release - > make -Cbuild -j4 install + > CC=gcc-8 CXX=g++8 \ + > cmake -H. -Bbuild \ + > -DCMAKE_BUILD_TYPE=Release \ + > -DFBXSDK_SDKS=/home/zell/FBXSDK + > make -Cbuild -j12 install ``` +Acquiring and installing GCC 8.* is a bit outside of the mandate for this +README, but on a Linux machine you might try: +``` + > sudo add-apt-repository ppa:ubuntu-toolchain-r/test + > sudo apt update + > sudo apt-get install gcc-8 g++-8 +``` + +and on Mac, Homebrew's stable GCC is at 8.3 at the time of writing. + If all goes well, you will end up with a statically linked executable. ### Windows @@ -141,12 +176,9 @@ install it and [run it](https://cmake.org/runningcmake/) on the FBX2glTF checkout (choose a build directory distinct from the source). As part of this process, you will be asked to choose which generator -to use. **At present, only Visual Studio 2017 is supported.** Older +to use. **At present, only Visual Studio 2019 is supported.** Older versions of the IDE are unlikely to successfully build the tool. -*(MinGW support is plausible. The difficulty is linking statically against the -FBX SDK .lib file. Contributions welcome.)* - Note that the `CMAKE_BUILD_TYPE` variable from the Unix Makefile system is entirely ignored here; it is when you open the generated solution that you will be choose one of the canonical build types — *Debug*,