Description

This PR implements the glTF extension KHR_materials_specular 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. These are then attached to the material. See the updates to the Material class in ModelComponents.

Note that GltfLoader has been refactored to better handle multiple PBR extensions. See the methods loadMetallicRoughness and loadSpecularGlossiness which have been pulled out of loadMaterial, as well as the new method loadSpecular which handles the new extension. As part of this refactoring, I reworked many of the relevant private methods to use smaller function signatures (taking advantage of properties stored on the loader) and added docstrings.

Processing the extension properties in the pipeline

In MaterialPipelineStage, if material.specular is defined, its properties are processed by the new method processSpecularUniforms, which is very similar to the existing methods processSpecularGlossinessUniforms and processMetallicRoughnessUniforms.

The specular 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.

The specular extension has some naming conflicts with the old specular glossiness extension. To avoid confusion, I added "legacy" to the specular glossiness names. For example, the existing uniform u_specularFactor becomes u_legacySpecularFactor, and the corresponding define HAS_SPECULAR_FACTOR becomes HAS_LEGACY_SPECULAR_FACTOR.

Using the extension in the shader

Most of the shader changes are in MaterialStageFS. The specularColorFactor (computed from both specularColorFactor and specularColorTexture is used to modify the f0 value in the czm_modelMaterial (which is somewhat unfortunately named material.specular).

The specularWeight (computed from specularFactor) is then passed through to pbrLighting and ImageBasedLightingStageFS.

Note that the implementation in ImageBasedLightingStageFS is incomplete, as the specularWeight factor is only used to scale down the specular component. The specularWeight factor should also modify the diffuse component in a more complicated way, but this will require some reworking of our image-based lighting calculations.

Other code style updates

Reduced nesting of compiler directives

Some of the material and lighting shader code was difficult to read due to deeply nested compiler directives. The readability problem was exacerbated by inconsistent indentation. For example, in MaterialStageFS, we had:

void materialStage(...)
{
    // ...
    #if defined(LIGHTING_PBR) && defined(USE_SPECULAR_GLOSSINESS)
        #ifdef HAS_SPECULAR_GLOSSINESS_TEXTURE
        vec2 specularGlossinessTexCoords = TEXCOORD_SPECULAR_GLOSSINESS;
          #ifdef HAS_SPECULAR_GLOSSINESS_TEXTURE_TRANSFORM
          specularGlossinessTexCoords = computeTextureTransform(specularGlossinessTexCoords, u_specularGlossinessTextureTransform);
          #endif

        vec4 specularGlossiness = czm_srgbToLinear(texture(u_specularGlossinessTexture, specularGlossinessTexCoords));
        vec3 specular = specularGlossiness.rgb;
        float glossiness = specularGlossiness.a;
            #ifdef HAS_SPECULAR_FACTOR
            specular *= u_specularFactor;
            #endif
// ...

One popular style guide recommends that all preprocessor directives start at the beginning of the line, and that the directives should not affect the indentation of the rest of the code. This would be a significant change to all our shaders, so I did not try to make that change now. Instead, I followed the example of the reference implementation, and tried to limit nesting to 2 levels, by adding subroutines. The above example from MaterialStageFS now becomes:

void setSpecularGlossiness(inout czm_modelMaterial material)
{
    #ifdef HAS_SPECULAR_GLOSSINESS_TEXTURE
        vec2 specularGlossinessTexCoords = TEXCOORD_SPECULAR_GLOSSINESS;
        #ifdef HAS_SPECULAR_GLOSSINESS_TEXTURE_TRANSFORM
            specularGlossinessTexCoords = computeTextureTransform(specularGlossinessTexCoords, u_specularGlossinessTextureTransform);
        #endif

        vec4 specularGlossiness = czm_srgbToLinear(texture(u_specularGlossinessTexture, specularGlossinessTexCoords));
        vec3 specular = specularGlossiness.rgb;
        float glossiness = specularGlossiness.a;
        #ifdef HAS_LEGACY_SPECULAR_FACTOR
            specular *= u_legacySpecularFactor;
        #endif
//...
void materialStage(...)
{
    // ...
    #if defined(LIGHTING_PBR) && defined(USE_SPECULAR_GLOSSINESS)
        setSpecularGlossiness(material);
    #elif //...

This affects both MaterialStageFS and ImageBasedLightingStageFS.

Cleaner loop structure

Some loops with pre-declared counters were cleaned up to better conform to the Coding Guide. This primarily affects GltfLoader.

Options object destructuring

While reading some functions with the arguments supplied as options objects, I found it easier to understand the arguments if I rewrote this:

  const gltfResource = options.gltfResource;
  const typedArray = options.typedArray;
  const releaseGltfJson = defaultValue(options.releaseGltfJson, false);
  const asynchronous = defaultValue(options.asynchronous, true);
  const incrementallyLoadTextures = defaultValue(
    options.incrementallyLoadTextures,
    true
  );
  // ...

as an object destructuring with default values, like this:

  const {
    gltfResource,
    typedArray,
    releaseGltfJson = false,
    asynchronous = true,
    incrementallyLoadTextures = true,
    // ...
  } = options;

This primarily affects GltfLoader, ResourceCache, and ResourceCacheKey.

Issue number and link

Resolves #11938.

Testing plan

Load the development Sandcastle glTF PBR Specular and compare 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 Sandcastle from server.
• Investigate color factor vs texture rendering differences
• Add image comparisons