From c194843239b9402653e992d9234c2da088fba793 Mon Sep 17 00:00:00 2001 From: Par Winzell Date: Thu, 19 Oct 2017 09:15:25 -0700 Subject: [PATCH] More helpful README update. --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 055f8e7..7d55980 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,82 @@ venerable [FBX](https://www.autodesk.com/products/fbx/overview) format to [glTF 2.0](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0), a modern runtime asset delivery format. -## Building & Running +Precompiled binaries releases may be +found [here](https://github.com/facebookincubator/FBX2glTF/releases). -This tool has been tested on Linux, Mac OS X and Windows. It requires CMake 3.5+ -and a reasonably C++11 compliant toolchain. +## Running + +The tool can be invoked like so: +``` + > FBX2glTF ~/models/butterfly.fbx +``` + +Or perhaps, as part of a more complex pipeline: +``` + > FBX2glTF --binary --draco --flip-v \ + --khr-materials-common \ + --input ~/models/source/butterfly.fbx \ + --output ~/models/target/butterfly.glb +``` + +### CLI Switches + +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...] [] + + -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. + --khr-materials-common (WIP) Use KHR_materials_common extensions to + specify Unlit/Lambert/Blinn/Phong shaders. + --pbr-metallic-roughness (WIP) Try to glean glTF 2.0 native PBR + attributes from the FBX. + --pbr-specular-glossiness + (WIP) Experimentally fill in the + KHR_materials_pbrSpecularGlossiness extension. + -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. +``` + +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. +- `--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 recommended. Your FBX is + likely constructed with the assumption that `(0, 0)` is bottom left, whereas + glTF has `(0, 0)` as top left. To produce spec-compliant glTF, you will want + to pass `--flip-v`. +- All three material options are, in their own way, works in progress. The + `--pbr-metallic-roughness` switch will be chosen by default if you supply + none of the others, and is the only one that produces glTF that does not + depend on an extension. It is documented further below, as is + `--khr-materials-common`. +- If you supply any `-keep-attribute` option, you enable a mode wherein you must + supply it repeatedly to list *all* the vertex attributes you wish to keep in + the conversion process. This is a way to trim the size of the resulting glTF + if you know the FBX contains superfluous attributes. The supported arguments + are `position`, `normal`, `tangent`, `color`, `uv0`, and `uv1`. + +## 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. We currently depend on the open source projects [Draco](https://github.com/google/draco), @@ -31,23 +103,11 @@ Compilation on Unix machines should be as simple as: ``` > cd - > cmake -H. -Bbuild - > make -Cbuild + > cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release + > make -Cbuild -j4 install ``` -If all goes well, you will end up with a statically linked executable that can -be invoked like so: -``` - > ./build/FBX2glTF ~/models/butterfly.fbx -``` - -Or perhaps, as part of a more complex pipeline: -``` - > ./build/FBX2glTF --binary --draco --flip-v \ - --khr-materials-common \ - --input ~/models/source/butterfly.fbx \ - --output ~/models/target/butterfly.glb -``` +If all goes well, you will end up with a statically linked executable. ### Windows