Implement glTF extension KHR_materials_anisotropy

[jjhembd]

Merge #11970 first!

Description

This PR implements the glTF extension KHR_materials_anisotropy in physically-based rendering of models.

How it works (and how it affects the code)

Parsing the extension at load time

When the glTF is loaded, GltfLoader reads factors and loads textures from the extension. See the new loadAnisotropy method, which is very similar to the loadSpecular method from #11970. The factors and textures are then attached to the material. See the updates to the Material class in ModelComponents.

Processing the extension properties in the pipeline

In MaterialPipelineStage, if material.anisotropy is defined, its properties are processed by the new method processAnisotropyUniforms, which is very similar to processSpecularUniforms. The sine and cosine of the anisotropyRotation factor are pre-computed, and combined with anisotropyStrength into one vec3 uniform.

The anisotropy extension, if used, will extend the metallic roughness model. As a result, the check for the extension usually takes place inside the same code branch that handles metallic-roughness processing.

Using the extension in the shader

The orientation of the anisotropic effect is defined relative to the "tangent" vector on the surface. The tangent vector is aligned in the direction of increasing u coordinate in the normal map. These tangent vectors are either supplied as a vertex attribute, or computed via derivatives of the normal map texture coordinates.

We already had code using and/or computing tangent vectors, but discarded the information early once the normals were prepared. To preserve the tangent information for anisotropic calculations, a new NormalInfo struct is defined, and returned from the new getNormalInfo function. Along the way, some of the tangent calculations were broken down into smaller functions to enable re-use for both the isotropic and anisotropic cases. The setAnisotropy function then stores the relevant anisotropic information on the material. See also the corresponding changes to the czm_modelMaterial and czm_pbrParameters structs.

The actual anisotropic lighting calculations can be found in pbrLighting and ImageBasedLightingStageFS. They only modify the specular reflection component of the final color.

Note that the implementation in ImageBasedLightingStageFS is complete only for the case of supplied environment maps in textureIBL. The proceduralIBL function will require a more significant rewrite as part of a wider IBL update, so the anisotropy calculation can be incorporated at that stage.

Other changes

• Minor cleanup in GeometryPipelineStage (done while tracing back normal calculations)
• Added more docstrings in MaterialPipelineStage
• Fixed normalization bug in ImageBasedLightingStageFS. See Normalization error in image-based lighting #11994

Issue number and link

Resolves #11976. Resolves #11994.

Testing plan

Load the development Sandcastle glTF PBR Anisotropy and toggle through the 4 testing models, comparing to the rendering in the reference implementation.

Author checklist

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have update the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

Other TODO:

• Load test dataset for the Sandcastle from a server
• Report normalization bug in IBL
• Describe code changes
• Add image comparisons
• Explain non-implementation in procedural IBL
• Clean up: use TBN matrix?

[github-actions]

Thank you for the pull request, @jjhembd!

✅ We can confirm we have a CLA on file for you.

[jjhembd]

Image comparisons

All images captured from the glTF PBR Anisotropy Sandcastle

"Barn lamp" test dataset

Before this PR:

With extension enabled. Notice the stretching of the specular reflection perpendicular to the brush marks in the metal.

Anisotropy strength test

Extension disabled:

Extension enabled:

Anisotropy disc test

The discs in each square are not visible without the extension.

[jjhembd]

@ggetz this is ready for review. But it is written on top of #11970 so we will want to merge that one first.

[ggetz]

I'm seeing this blown-out areas on the barn lamp sample model when using non-procedural IBL:

It appears to be related to the image we're using for IBL, but is it expected to be this extreme? Or is this something that will be fixed with the model IBL follow up?

[ggetz]

I'm getting the following error when running this test:

     RuntimeError: Fragment shader failed to compile.  Compile log: ERROR: 0:467: 'normalTexCoords' : undeclared identifier
ERROR: 0:467: 'computeTangent' : no matching overloaded function found
ERROR: 0:467: '=' : dimension mismatch
ERROR: 0:467: '=' : cannot convert from 'const mediump float' to 'highp 3-component vector of float'

[jjhembd]

This was an error in my test dataset. For this extension, either tangents or a normal map are required.

[ggetz]

Got it. Can we catch this early and provide a better error message?

[ggetz]

Thanks @jjhembd! I left a few comments, but overall this looks close.

[jjhembd]

Thanks for the feedback @ggetz! I think I addressed everything.
I also see the rendering artifacts in the "barn lamp" sample model. It almost looks like our environment map is not normalized correctly. The artifacts appear even before this PR, so I think it is something we should look at as part of the IBL work.

[ggetz]

@jjhembd All TODO's have been completed and this is ready to merge, correct?

[jjhembd]

@jjhembd All TODO's have been completed and this is ready to merge, correct?

@ggetz Yes, the only comment I haven't addressed is your question about whether we can catch a problem with a glTF that is not according to spec. I looked at this, but it is non-trivial.

We often ask users to run problematic models through the glTF-Validator. Would that be appropriate for this case, or do we want CesiumJS to identify model problems?

[ggetz]

Your question about whether we can catch a problem with a glTF that is not according to spec. I looked at this, but it is non-trivial.

OK to skip this if it blows up the scope of this PR. Better error messages for models that do not conform to spec is something we've mentioned before, but I understand there's a trade off in terms of effort and performance.