Ogre Next (aka v2) JSON material support (#178)

 - Added ogre.materialsv2json module with dot_materialsv2json() with
   same usage as ogre.material.dot_materials()
 - Support for a metallic workflow only via PrincipledBSDFWrapper
   - Sets the diffuse, emissive, metalness, roughness, specular,
     transparency, alpha_test, two_sided and workflow as required
   - Leaves default the blendblock, macroblock, sampler,
     shadow_const_bias, brdf, detail_diffuse[x], detail_normal[x],
     detail_weight[x], fresnel, receive_shadows, reflection

 - Uses material.gather_metallic_roughness_texture()
 - Implements channel separation in util.image_magick()

MaterialsJSON.md

@@ -0,0 +1,72 @@
+# OGRE Next JSON Materials
+Support implemented based on the Ogre Next documentation.
+https://ogrecave.github.io/ogre-next/api/latest/hlmspbsdatablockref.html
+
+Only the metallic workflow is supported at this time.
+
+## Metallic Workflow
+Metalness texture fetching expects a single image with the metal
+texture in the Blue channel and the roughness texture in the Green
+channel. The channels are expected to have been split via a 'Separate RGB' node
+before passing to the Principled BSDF. This is in line with the glTF standard
+setup.
+
+## Specular Workflow
+Unsupported.
+
+## Unsupported features
+
+### emissive.use_emissive_lightmap
+This requires features only found in Blender 2.9+
+
+### fresnel
+This is used in the Specular workflows supported by Ogre. Right now we
+only support the metallic workflow.
+
+### blendblock
+Blendblocks are used for advanced effects and don't fit into the
+standard Blender workflow. One commmon use would be to have better
+alpha blending on complex textures. Limit of 32 blend blocks at
+runtime also means we shouldn't "just generate them anyway."
+doc: https://ogrecave.github.io/ogre-next/api/latest/hlmsblendblockref.html
+
+### macroblock
+Macroblocks are used for advanced effects and don't fit into the
+standard Blender workflow. One common use would be to render a skybox
+behind everything else in a scene. Limit of 32 macroblocks at runtime
+also means we shouldn't "just generate them anyway."
+doc: https://ogrecave.github.io/ogre-next/api/latest/hlmsmacroblockref.html
+
+### sampler
+Samplerblocks are used for advanced texture handling like filtering,
+addressing, LOD, etc. These settings have signifigant visual and
+performance effects. Limit of 32 samplerblocks at runtime also means
+we shouldn't "just generate them anyway."
+
+### recieve_shadows
+No receive shadow setting in Blender 2.8+ but was available in 2.79.
+We leave this unset which defaults to true. Maybe add support in
+the 2.7 branch?
+See: https://docs.blender.org/manual/en/2.79/render/blender_render/materials/properties/shadows.html#shadow-receiving-object-material
+
+### shadow_const_bias
+Leave shadow const bias undefined to default. It is usually used to
+fix specific self-shadowing issues and is an advanced feature.
+
+### brdf
+Leave brdf undefined to default. This setting has huge visual and
+performance impacts and is for specific use cases.
+doc: https://ogrecave.github.io/ogre-next/api/latest/hlmspbsdatablockref.html#dbParamBRDF
+
+### reflection
+Leave reflection undefined to default. In most cases for reflections
+users will want to use generated cubemaps in-engine.
+
+### detail_diffuse[0-3]
+Layered diffuse maps for advanced effects.
+
+### detail_normal[0-3]
+Layered normal maps for advanced effects.
+
+### detail_weight
+Texture acting as a mask for the detail maps.

README.md

@@ -69,6 +69,9 @@ The active object selection is when there is an object with a yellow outline (in
 Check out all the exporter and importer options in the [Options Document](Options.md)
 
 ### Materials
+Materials will be exported as OGRE 1.x material files or as OGRE Next material.json files as required.
+
+#### OGRE 1.x Materials
 Materials are exported as RTSS OGRE 1.x materials (unless "Fixed Function Parameters" is selected).
 The following textures are exported: Base Color, Metallic and Roughness, Normal Map and Emission. Baked Ambient Occlusion is not supported for the moment.
 
@@ -77,6 +80,13 @@ Except for the Emission texture, where the Emission input of the Principled BSDF
 
 A good example of how the material should be setup for best results is the "Damaged Helmet" model found here: https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/DamagedHelmet
 
+#### OGRE Next JSON Materials
+The current OGRE Next JSON exporter only explicitly supports a metalness workflow, however it will attempt to export materials not following that workflow regardless and *may* produce passable results.
+
+For materials using metalness it expects a single image with the blue channel containing the metalness map and the green channel containing the roughness map fed into the Principled BSDF via a Separate RGB node. Not following this convention will print a warning to the console and the exported materials will likely not appear correctly when rendered.
+
+There are numerous features in the Ogre Next JSON format that are not directly supported, see the [Materials JSON](MaterialsJSON.md) notes for details.
+
 ### Blender Modifiers Support
 Blender has some very useful modifiers, and most of them are supported by `blender2ogre` but not all of them.
 Check out the [Blender Modifiers Support Page](Modifiers.md) to check out the list and also some recommendations about them.

io_ogre/api.py

@@ -1,6 +1,7 @@
 from .ogre.mesh import dot_mesh
 from .ogre.skeleton import dot_skeleton
 from .ogre.material import dot_material
+from .ogre.materialv2json import dot_materialsv2json
 from .ogre.scene import dot_scene
 
 # import various functions that can be used to export objects