Gltf-blender-io: Documentation

[donmccurdy]

The Blender release notes currently link to the documentation from glTF-Blender-Exporter, which focus on the (no longer necessary) custom Cycles nodes. We should create new documentation within this project, covering at least:

• Principled BSDF supported features and node arrangements
• Transparency and alpha
• Animation
  
  
  
  • How to export multiple animations
  
  
  • Which armature/skinning configurations are supported
  
  
• How to test a model and report bugs

[UX3D-nopper]

This week focus is on mainly fixing bugs and gets things stable for Blender 2.8.
In december, we will do the documentation.

[donmccurdy]

Thanks!

[donmccurdy]

Draft documentation: https://gltf-blender-io-docs-gbueavkvns.now.sh/addons/io_gltf2.html

A few TODOs:

• [x] Documentation reflects the reorganized export options (https://github.com/KhronosGroup/glTF-Blender-IO/pull/122)
• [x] The suggested "unlit" workflow does not actually work right now. I'm not sure what is the right solution there.
• [x] I haven't tested the animation workflows recently, but we should confirm the three options described ((a) make it the active Action on the object, (b) create a single-strip NLA track, or (c) stash the action) are still correct.
• [x] @julienduroure could you suggest descriptions for the Importer options?

[donmccurdy]

Updated documentation: https://gltf-blender-io-docs-fuznnktuig.now.sh/addons/io_gltf2

@julienduroure thanks for adding the importer option descriptions!

@julienduroure @UX3D-nopper Could you take a look at this and suggest any changes you'd prefer? The draft is pushed to https://github.com/KhronosGroup/glTF-Blender-IO/blob/master/docs/io_gltf2.rst. I've omitted the Unlit workflow, since that is still in progress. Once everything looks good I'll try merging the docs into the Blender repo.

[donmccurdy]

/cc @emackey

[julienduroure]

Currently, only KHR_materials_pbrSpecularGlossiness is supported by importer. I saw that Norbert added details about importer/exporter support, but removed them later.

[donmccurdy]

@julienduroure Not sure I understand, do you mean that spec/gloss is supported by the importer and not the exporter? Or that the importer supports spec/gloss, but not metal/rough and unlit?

[julienduroure]

@donmccurdy I was talking about extension supported by importer. That means that importer supports metal/rough (core glTF) & spec/gloss (KHR_materials_pbrSpecularGlossiness extension), but not unlit, not ponctual lights, not texture transfom.

Hope I will have time in January to add these supports

[donmccurdy]

I see, thanks! I'll update the docs.

EDIT: done --> https://github.com/KhronosGroup/glTF-Blender-IO/commit/8cde7bfa3f6f9bb6f6cc6f69f0577f4eb955b9b8

[julienduroure]

For info, I just get commit rights on Blender documentation.
I have to setup stuff before be able to commit, but should be done in following days/weeks

[julienduroure]

Note that I still don't have wiki account, so change logs are still linking to wrong url, but I will ask someone to change it, or to create me a wiki account

[julienduroure]

Documentation is now committed into Blender doc \o/
I don't know how many time it will take to be online (I don't know how frequently they build the doc)

Next steps:

• [ ] Update the doc. I pushed an image about unlit, but is not used yet
• [ ] After the doc is built, ask someone to change "change logs"

[donmccurdy]

Awesome, thank you! :)

I'm not sure what to write for Unlit documentation at the moment; I think we'll want the exporter to treat an Emissive node – in a material _without_ a Principled node – as unlit. Once that change is in the importer and exporter should be roundtrip compatible and we can document it.

[donmccurdy]

@julienduroure do you think it's worthwhile to keep the documentation in GitHub (https://github.com/KhronosGroup/glTF-Blender-IO/blob/master/docs/blender_docs/io_gltf2.rst), in addition to the Blender repository? The RST formatting doesn't look quite right on GitHub, and the images aren't visible, so I'm wondering if having docs only in the Blender repository might be easier.

[donmccurdy]

Docs are live! 🎊

https://docs.blender.org/manual/en/dev/addons/io_gltf2.html