Ogre_glTF: A glTF loader plugin for Ogre 2.x

By Ybalrid

- 8 minutes read - 1653 words

If there’s one open source library that I really like and think has a great level of usefulness for both myself, and a whole community, it’s Ogre.

Before going on the story of why I felt loading glTF files into ogre was a necessary thing to do, and why I decided to actually write a loader myself, I need to tell you a bit about Ogre:

Good old Ogre3D

I prefer to write it “Ogre”, but really, it’s name is OGRE. This is an acronym that stands for “Object-oriented Graphical Rendering Engine”.

Ogre existed for ages, and is a well regarded 3D rendering engine. The main advantages of Ogre are:

  • Its code base is stable,
  • It’s full of features,
  • It’s cross-platform,
  • It only exposes to you a simple scene graph, abstracting away any graphics API the system is using,
  • Has a simple “resource manager” to get your 3D objects and textures,
  • And is graphics API agnostic. Through Ogre’s public API you can choose the backend (called a “RenderSystem”) to use between OpenGL, Direct 3D, Metal…

This last point means that when using Ogre’s public API, you don’t need to know about the way to talk to the GPU, and your code should work the same whenever the rendering is happening thanks to OpenGL, Direct3D, Metal, or whatever else it could be supporting.

Recently (few years ago now), Ogre development has been pushed in a new direction in a parallel branch that is called Ogre 2.x. As far as I can tell, this is mostly the work of Matías N. Goldberg{.ProfileHeaderCard-nameLink.u-textInheritColor.js-nav}.

This new branch is focused on modernizing Ogre. Doing so by removing a lot of overhead from the original design. (Ogre was really “design pattern” focused, exposing listeners for pretty much anything, lots of virtual calls…) This is done in several ways: by adopting new best practices for performance like starting to use concept of DOD, using half precision floating point number where it doesn’t hurt, improving usage of caches, using AZDO (Approaching Zero Driver Overhead) techniques in the renderers, remove pointless preprocessing when modern hardware where now the more simpler and direct approaches can be faster… And a lot of things I’m less familiar with to be honest.

But the performance boost can be really significant, notably on CPU bound situations, Ogre now does really better usage of your CPU time in large scenes with instantiated objects and lots of nodes in the scene graph to go through.

What I was really interested about when upgrading to Ogre 2.1 was the introduction of a new “material” system in Ogre 2. It’s called HLMS, and stands for the “High Level Material System”. It is a shader preprocessor/template system where the definition of a material will generate the shader code needed to render it, using a a set of fixed parameters.

This replaces the older “dynamically generated” shader system Ogre used to have called RTSS (Run-Time Shader System). One of the main advantages of HLMS is a really simplified syntax for the end user, and the fact that it’s main goal is not to emulate an old fixed-function pipeline, like RTSS was originally conceived for.

Speaking of modernity, HLMS comes with two standard implementation (You can modify them/write your own if you know shader programming): Unlit and PBS. (with a “mobile” versions of each)

Unlit, like it’s name suggest, is the simplest thing a material can do. It only defines the color values of pixels, and doesn’t do any shading. This is intended to be used for things like UI interface, HUDs, overlays, things along those lines

PBS stands for Physically Based Shading. This is what most of the industry would refer to as “PBR”. (R for “Rendering”. There’s a distinction between them, Shading is one part of “Rendering” in general). The HLMS PBS implementation in Ogre 2.x is comparable to the standard PBR material you’ll find in Unreal Engine, and many other. It uses standard physical parameters to describe how light interact with the surface.

This is all fine and dandy, but, at least at the time I started working on the glTF plugin (about a year ago now), there was no way to export, for example, from blender, a Ogre 2.x “.mesh” file with an accompanying “.material” that would be compatible with the new HLMS system.

This would have not been a problem if Ogre could just load glTF assets. As explained in my previous article, glTF is a 3D file format that represent 3D assets (and even full scenes if you want!) including meshes, animations, textures and PBR Material. The material in question using a standar “metal-roughness” workflow (more explanations on the excellent guide from Allegorithmic, the makers of Substance).

glTF being an industry standard file format, we don’t need to rely on an up-to-date exporter for multiple 3D modeling software being able to produce files compatible with the current version of Ogre, and being able to correctly translate material definitions and animations tracks to Ogre.

This is what I thought, and this is the reason why I started working on a glTF loader for Ogre.

Loading glTF in practice

A glTF asset is either one or multiple files that are composed of 3 parts:

  • A JSON object containing metadata about the scenes, nodes, meshes, material, animation and everything inside the asset
  • Binary buffers containing raw vertex/index/animation data
  • Image assets containing textures

A .gltf file is a simple JSON file, either containing base64, data URI, or URLs pointing to binary buffers (generally in .bin files) and images.

A .glb file is a binary file containing a standard header, followed by the JSON metadata in ASCII text, followed by every binary data required (including images).

In my Ogre_glTF plugin, I choose to rely on TinyGLTF to handle the parsing and loading of the images and binary data. TinyGLTF is header only and itself uses STB libraries for image loading and (currently, this is subject to change relatively soon) Niels Lohmann JSON library for modern C++.

To avoid any problems with the fact that TinyGLTF will include a JSON loader and other libraries as header only, and that the plugin will need to enclose the implementation of these things, the plugin follows the pimpl idiom. The only headers required are the ones shipped with the built plugin, and all the internal implementation is inside the dynamic library.

The plugin itself is built as a standard dynamic library that has a pluginized for Ogre afterwards. This permit you to either dynamically load it as an Ogre plugin (and maybe have conditional support for it) or to link it as a regular dynamic library and bypass the Ogre plugin system all together.

The repository for the Ogre plugin is hosted at https://github.com/Ybalrid/Ogre_glTF

Code is hosted on GitHub, under the MIT license, and at the time of writing this, we are at this commit.

I expect most people to use it as an Ogre plugin (as it is way simpler. You will probably just need to copy a few header files around and add a line in a “plugins.cfg” if you are using the regular Ogre framework for configuration). There are two example programs that loads random files chosen from the sample collection from Khronos, one that use the library by itself, and another one that loads it as a plugin.

The plugin is currently alpha software quality, but is promising. Iis available in a version 0.2.1 at the time or writing. and is compatible with the head of the v2-1 branch of Ogre.

Plans for the future is to rewrite the texture and material loading code to make it compatible with Ogre v2-2, but I cannot give an ETA on this.

The plugin is for now limited into being a “model” loader, intended as using .glb files as replacement for Ogre “.mesh + .skeleton + .material” classic resource format.

The plugin’s functionality includes:

  • Loading glTF meshes and create v2 “mesh” objects in Ogre MeshManager (including Draco compressed meshes).
  • Loading glTF skin metadata and create Ogre skeleton objects.
  • Loading glTF animations track for a given skeleton and adding them as skeleton animations into Ogre.
  • Loading glTF materials (standard metal-rougness workflow) and create HlmsPbs Datablock for Ogre v2. The plugin doesn’t support the Specular-Glossiness glTF extension.
  • Loading images in glTF assets and create texture out of them.
  • “Remuxing” textures from glTF into texture usable by HlmsPbs. Including separating the metalness and roughness maps into gray-scale images.
  • Adding a ResouceManager in Ogre’s ResourceGroupManager that retrieve .glb files from Ogre’s resource groups and get them through the “load mesh – load textures – load materials” pipeline to get Ogre Meshes and Items.

This is the most useful open-source project that I have ever started, and the one that has received the most contribution and interest from the community. I am really pleased with that yet.

For the projects future development, there’s a number of features that would be really valuable to have in the plugin, notably the support for a number of glTF extensions that may be used often in future assets, notably ones directly developed by khronos:

  • KHR_materials_pbrSpecularGlossiness to support the other common PBR workflow using specular and gloss values
  • KHR_materials_unlit to translate unlit materials into HlmsUnlit datablocks
  • KHR_texture_transform to be able to factor a scale and translation when reading texture coordinates, to load some types of texture atlases

I may also extend the scope of this plugin to make it a scene loader, not just an “object” loader. This would allow to directly use a 3D modeling software to create scenes and environments, but I haven’t decided on that.

And the only real missing feature is the loading of morph targets animations. Currently Ogre 2.x does not support animation targets in the v2-1 or v2-2 branches. I know somebody was working on this some time ago, and had support for that in OpenGL and metal, but last time I’ve checked this person had closed his pull request.