engine: move setFrontFaceWindingInverted from View to MaterialInstance (

google#7331)

Moving setFrontFaceWindingInverted to MaterialInstance will enable
finer control over face inversion and aligns better with Vulkan's
pipeline definition (see VkGraphicsPipelineCreateInfo).

NEW_RELEASE_NOTES.md

@@ -16,3 +16,4 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 - engine: Add `Material::getFeatureLevel()`
 - engine: Add missing `Material::getReflectionMode()` method in Java
 - engine: Support basic usage of post-processing materials on feature level 0
+- engine: move `setFrontFaceWindingInverted` from `View` to `MaterialInstance` [**API CHANGE**]

android/filament-android/src/main/cpp/MaterialInstance.cpp

@@ -433,6 +433,13 @@ Java_com_google_android_filament_MaterialInstance_nSetStencilWriteMask(JNIEnv*,
     instance->setStencilWriteMask(writeMask, static_cast<MaterialInstance::StencilFace>(face));
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetFrontFaceWindingInverted(JNIEnv*,
+        jclass, jlong nativeMaterialInstance, jboolean inverted) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setFrontFaceWindingInverted(inverted);
+}
+
 extern "C"
 JNIEXPORT jstring JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetName(JNIEnv* env, jclass,
@@ -469,78 +476,85 @@ extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetMaskThreshold(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->getMaskThreshold();
 }
 
 extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingVariance(JNIEnv* env,
         jclass clazz, jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->getSpecularAntiAliasingVariance();
 }
 
 extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingThreshold(JNIEnv* env,
         jclass clazz, jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->getSpecularAntiAliasingThreshold();
 }
 
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDoubleSided(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->isDoubleSided();
 }
 
 extern "C"
 JNIEXPORT jint JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetCullingMode(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return (jint)instance->getCullingMode();
 }
 
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsColorWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->isColorWriteEnabled();
 }
 
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDepthWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->isDepthWriteEnabled();
 }
 
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsStencilWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->isStencilWriteEnabled();
 }
 
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDepthCullingEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return instance->isDepthCullingEnabled();
 }
 
 extern "C"
 JNIEXPORT jint JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetDepthFunc(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     return (jint)instance->getDepthFunc();
 }
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsFrontFaceWindingInverted(JNIEnv*,
+        jclass, jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    return static_cast<jboolean>(instance->isFrontFaceWindingInverted());
+}

android/filament-android/src/main/cpp/View.cpp

@@ -202,20 +202,6 @@ Java_com_google_android_filament_View_nIsPostProcessingEnabled(JNIEnv*,
     return static_cast<jboolean>(view->isPostProcessingEnabled());
 }
 
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_View_nSetFrontFaceWindingInverted(JNIEnv*,
-        jclass, jlong nativeView, jboolean inverted) {
-    View* view = (View*) nativeView;
-    view->setFrontFaceWindingInverted(inverted);
-}
-
-extern "C" JNIEXPORT jboolean JNICALL
-Java_com_google_android_filament_View_nIsFrontFaceWindingInverted(JNIEnv*,
-        jclass, jlong nativeView) {
-    View* view = (View*) nativeView;
-    return static_cast<jboolean>(view->isFrontFaceWindingInverted());
-}
-
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetAmbientOcclusion(JNIEnv*, jclass, jlong nativeView, jint ordinal) {
     View* view = (View*) nativeView;

android/filament-android/src/main/java/com/google/android/filament/MaterialInstance.java

@@ -850,6 +850,32 @@ public void setStencilWriteMask(int writeMask) {
         setStencilWriteMask(writeMask, StencilFace.FRONT_AND_BACK);
     }
 
+    /**
+     * Returns true if front face winding order is inverted.
+     *
+     * @see #setFrontFaceWindingInverted
+     */
+    public boolean isFrontFaceWindingInverted() {
+        return nIsFrontFaceWindingInverted(getNativeObject());
+    }
+
+    /**
+     * Inverts the winding order of front faces. By default front faces use a counter-clockwise
+     * winding order. When the winding order is inverted, front faces are faces with a clockwise
+     * winding order.
+     *
+     * Changing the winding order will directly affect the culling mode in materials
+     * (see Material#getCullingMode).
+     *
+     * Inverting the winding order of front faces is useful when rendering mirrored reflections
+     * (water, mirror surfaces, front camera in AR, etc.).
+     *
+     * @param inverted True to invert front faces, false otherwise.
+     */
+    public void setFrontFaceWindingInverted(boolean inverted) {
+        nSetFrontFaceWindingInverted(getNativeObject(), inverted);
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed MaterialInstance");
@@ -941,6 +967,9 @@ private static native void nSetStencilReadMask(long nativeMaterialInstance, int
     private static native void nSetStencilWriteMask(long nativeMaterialInstance, int writeMask,
             long face);
 
+    private static native void nSetFrontFaceWindingInverted(long nativeView, boolean inverted);
+    private static native boolean nIsFrontFaceWindingInverted(long nativeView);
+
     private static native String nGetName(long nativeMaterialInstance);
     private static native long nGetMaterial(long nativeMaterialInstance);
 

android/filament-android/src/main/java/com/google/android/filament/View.java

@@ -709,32 +709,6 @@ public void setPostProcessingEnabled(boolean enabled) {
         nSetPostProcessingEnabled(getNativeObject(), enabled);
     }
 
-    /**
-     * Returns true if post-processing is enabled.
-     *
-     * @see #setPostProcessingEnabled
-     */
-    public boolean isFrontFaceWindingInverted() {
-        return nIsFrontFaceWindingInverted(getNativeObject());
-    }
-
-    /**
-     * Inverts the winding order of front faces. By default front faces use a counter-clockwise
-     * winding order. When the winding order is inverted, front faces are faces with a clockwise
-     * winding order.
-     *
-     * Changing the winding order will directly affect the culling mode in materials
-     * (see Material#getCullingMode).
-     *
-     * Inverting the winding order of front faces is useful when rendering mirrored reflections
-     * (water, mirror surfaces, front camera in AR, etc.).
-     *
-     * @param inverted True to invert front faces, false otherwise.
-     */
-    public void setFrontFaceWindingInverted(boolean inverted) {
-        nSetFrontFaceWindingInverted(getNativeObject(), inverted);
-    }
-
     /**
      * Sets options relative to dynamic lighting for this view.
      *
@@ -1211,8 +1185,6 @@ void clearNativeObject() {
     private static native void nSetColorGrading(long nativeView, long nativeColorGrading);
     private static native void nSetPostProcessingEnabled(long nativeView, boolean enabled);
     private static native boolean nIsPostProcessingEnabled(long nativeView);
-    private static native void nSetFrontFaceWindingInverted(long nativeView, boolean inverted);
-    private static native boolean nIsFrontFaceWindingInverted(long nativeView);
     private static native void nSetAmbientOcclusion(long nativeView, int ordinal);
     private static native int nGetAmbientOcclusion(long nativeView);
     private static native void nSetAmbientOcclusionOptions(long nativeView, float radius, float bias, float power, float resolution, float intensity, float bilateralThreshold, int quality, int lowPassFilter, int upsampling, boolean enabled, boolean bentNormals, float minHorizonAngleRad);

filament/include/filament/MaterialInstance.h

@@ -480,6 +480,27 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
     void setStencilWriteMask(uint8_t writeMask,
             StencilFace face = StencilFace::FRONT_AND_BACK) noexcept;
 
+    /**
+     * Inverts the winding order of front faces. By default front faces use a counter-clockwise
+     * winding order. When the winding order is inverted, front faces are faces with a clockwise
+     * winding order.
+     *
+     * Changing the winding order will directly affect the culling mode in materials
+     * (see Material::getCullingMode()).
+     *
+     * Inverting the winding order of front faces is useful when rendering mirrored reflections
+     * (water, mirror surfaces, front camera in AR, etc.).
+     *
+     * @param inverted True to invert front faces, false otherwise.
+     */
+    void setFrontFaceWindingInverted(bool inverted) noexcept;
+
+    /**
+     * Returns true if the winding order of front faces is inverted.
+     * See setFrontFaceWindingInverted() for more information.
+     */
+    bool isFrontFaceWindingInverted() const noexcept;
+
 protected:
     // prevent heap allocation
     ~MaterialInstance() = default;

filament/include/filament/View.h

@@ -629,27 +629,6 @@ class UTILS_PUBLIC View : public FilamentAPI {
     //! Returns true if post-processing is enabled. See setPostProcessingEnabled() for more info.
     bool isPostProcessingEnabled() const noexcept;
 
-    /**
-     * Inverts the winding order of front faces. By default front faces use a counter-clockwise
-     * winding order. When the winding order is inverted, front faces are faces with a clockwise
-     * winding order.
-     *
-     * Changing the winding order will directly affect the culling mode in materials
-     * (see Material::getCullingMode()).
-     *
-     * Inverting the winding order of front faces is useful when rendering mirrored reflections
-     * (water, mirror surfaces, front camera in AR, etc.).
-     *
-     * @param inverted True to invert front faces, false otherwise.
-     */
-    void setFrontFaceWindingInverted(bool inverted) noexcept;
-
-    /**
-     * Returns true if the winding order of front faces is inverted.
-     * See setFrontFaceWindingInverted() for more information.
-     */
-    bool isFrontFaceWindingInverted() const noexcept;
-
     /**
      * Enables use of the stencil buffer.
      *

filament/src/MaterialInstance.cpp

@@ -340,4 +340,12 @@ bool MaterialInstance::isDepthCullingEnabled() const noexcept {
     return downcast(this)->isDepthCullingEnabled();
 }
 
+void MaterialInstance::setFrontFaceWindingInverted(bool inverted) noexcept {
+    downcast(this)->setFrontFaceWindingInverted(inverted);
+}
+
+bool MaterialInstance::isFrontFaceWindingInverted() const noexcept {
+    return downcast(this)->isFrontFaceWindingInverted();
+}
+
 } // namespace filament

filament/src/RenderPass.cpp

@@ -323,7 +323,7 @@ void RenderPass::instanceify(FEngine& engine) noexcept {
 UTILS_ALWAYS_INLINE // this function exists only to make the code more readable. we want it inlined.
 inline              // and we don't need it in the compilation unit
 void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
-        FMaterialInstance const* const UTILS_RESTRICT mi, bool inverseFrontFaces) noexcept {
+        FMaterialInstance const* const UTILS_RESTRICT mi, bool invertedFrontFaces) noexcept {
 
     FMaterial const * const UTILS_RESTRICT ma = mi->getMaterial();
     variant = Variant::filterVariant(variant, ma->isVariantLit());
@@ -359,7 +359,7 @@ void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
     cmdDraw.primitive.rasterState.blendFunctionDstAlpha = blendingMustBeOff ?
             BlendFunction::ZERO : cmdDraw.primitive.rasterState.blendFunctionDstAlpha;
 
-    cmdDraw.primitive.rasterState.inverseFrontFaces = inverseFrontFaces;
+    cmdDraw.primitive.rasterState.inverseFrontFaces = invertedFrontFaces;
     cmdDraw.primitive.rasterState.culling = mi->getCullingMode();
     cmdDraw.primitive.rasterState.colorWrite = mi->isColorWriteEnabled();
     cmdDraw.primitive.rasterState.depthWrite = mi->isDepthWriteEnabled();
@@ -458,7 +458,6 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
     auto const* const UTILS_RESTRICT soaInstanceInfo        = soa.data<FScene::INSTANCES>();
 
     const bool hasShadowing = renderFlags & HAS_SHADOWING;
-    const bool viewInverseFrontFaces = renderFlags & HAS_INVERSE_FRONT_FACES;
     const bool hasInstancedStereo = renderFlags & IS_STEREOSCOPIC;
 
     Command cmdColor;
@@ -513,7 +512,6 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
         const uint32_t distanceBits = reinterpret_cast<uint32_t&>(distance);
 
         // calculate the per-primitive face winding order inversion
-        const bool inverseFrontFaces = viewInverseFrontFaces ^ soaVisibility[i].reversedWindingOrder;
         const bool hasMorphing = soaVisibility[i].morphing;
         const bool hasSkinningOrMorphing = soaVisibility[i].skinning || hasMorphing;
 
@@ -551,7 +549,6 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
                     soaInstanceInfo[i].count | PrimitiveInfo::USER_INSTANCE_MASK;
             cmdDepth.primitive.instanceBufferHandle = soaInstanceInfo[i].handle;
             cmdDepth.primitive.materialVariant.setSkinning(hasSkinningOrMorphing);
-            cmdDepth.primitive.rasterState.inverseFrontFaces = inverseFrontFaces;
 
             if (UTILS_UNLIKELY(hasInstancedStereo)) {
                 cmdColor.primitive.instanceCount =
@@ -563,8 +560,9 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
             renderableVariant.setFog(soaVisibility[i].fog && Variant::isFogVariant(variant));
         }
 
-        const bool shadowCaster = soaVisibility[i].castShadows & hasShadowing;
-        const bool writeDepthForShadowCasters = depthContainsShadowCasters & shadowCaster;
+        bool const shadowCaster = soaVisibility[i].castShadows & hasShadowing;
+        bool const writeDepthForShadowCasters = depthContainsShadowCasters & shadowCaster;
+        bool const reverseWindingOrder = soaVisibility[i].reversedWindingOrder;
 
         const Slice<FRenderPrimitive>& primitives = soaPrimitives[i];
         const FRenderableManager::SkinningBindingInfo& skinning = soaSkinning[i];
@@ -579,10 +577,11 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
             auto const& morphTargets = morphing.targets[pi];
             FMaterialInstance const* const mi = primitive.getMaterialInstance();
             FMaterial const* const ma = mi->getMaterial();
+            bool const invertedFrontFaces = mi->isFrontFaceWindingInverted() ^ reverseWindingOrder;
 
             if constexpr (isColorPass) {
                 cmdColor.primitive.primitiveHandle = primitive.getHwHandle();
-                RenderPass::setupColorCommand(cmdColor, renderableVariant, mi, inverseFrontFaces);
+                RenderPass::setupColorCommand(cmdColor, renderableVariant, mi, invertedFrontFaces);
 
                 cmdColor.primitive.skinningHandle = skinning.handle;
                 cmdColor.primitive.skinningOffset = skinning.offset;
@@ -611,7 +610,6 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
                     cmdColor.key |= makeField(primitive.getBlendOrder(),
                             BLEND_ORDER_MASK, BLEND_ORDER_SHIFT);
 
-
                     const TransparencyMode mode = mi->getTransparencyMode();
 
                     // handle transparent objects, two techniques:
@@ -689,6 +687,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
                 cmdDepth.primitive.primitiveHandle = primitive.getHwHandle();
                 cmdDepth.primitive.mi = mi;
                 cmdDepth.primitive.rasterState.culling = mi->getCullingMode();
+                cmdDepth.primitive.rasterState.inverseFrontFaces = invertedFrontFaces;
 
                 cmdDepth.primitive.skinningHandle = skinning.handle;
                 cmdDepth.primitive.skinningOffset = skinning.offset;

filament/src/RenderPass.h

@@ -264,8 +264,7 @@ class RenderPass {
 
     using RenderFlags = uint8_t;
     static constexpr RenderFlags HAS_SHADOWING           = 0x01;
-    static constexpr RenderFlags HAS_INVERSE_FRONT_FACES = 0x02;
-    static constexpr RenderFlags IS_STEREOSCOPIC         = 0x04;
+    static constexpr RenderFlags IS_STEREOSCOPIC         = 0x02;
 
     // Arena used for commands
     using Arena = utils::Arena<
@@ -416,11 +415,11 @@ class RenderPass {
             Variant variant, RenderFlags renderFlags, FScene::VisibleMaskType visibilityMask,
             math::float3 cameraPosition, math::float3 cameraForward) noexcept;
 
-    static void setupColorCommand(Command& cmdDraw, Variant variant,
-            FMaterialInstance const* mi, bool inverseFrontFaces) noexcept;
+    static void setupColorCommand(Command& cmdDraw, Variant variant, FMaterialInstance const* mi,
+            bool invertedFrontFaces) noexcept;
 
-    static void updateSummedPrimitiveCounts(
-            FScene::RenderableSoa& renderableData, utils::Range<uint32_t> vr) noexcept;
+    static void updateSummedPrimitiveCounts(FScene::RenderableSoa& renderableData,
+            utils::Range<uint32_t> vr) noexcept;
 
     // a reference to the Engine, mostly to get to things like JobSystem