Move stereoscopic debug options to Settings framework (#7347)

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

@@ -435,6 +435,13 @@ Java_com_google_android_filament_Engine_nIsAutomaticInstancingEnabled(JNIEnv*, j
     return (jboolean)engine->isAutomaticInstancingEnabled();
 }
 
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_nGetMaxStereoscopicEyes(JNIEnv*, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jlong) engine->getMaxStereoscopicEyes();
+}
+
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Engine_nGetSupportedFeatureLevel(JNIEnv *, jclass,
         jlong nativeEngine) {
@@ -477,7 +484,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
 extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*,
         jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB,
         jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB,
-        jlong jobSystemThreadCount) {
+        jlong jobSystemThreadCount, jlong stereoscopicEyeCount) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     Engine::Config config = {
             .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -486,6 +493,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .minCommandBufferSizeMB = (uint32_t) minCommandBufferSizeMB,
             .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
             .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
+            .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
     };
     builder->config(&config);
 }

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

@@ -480,6 +480,17 @@ Java_com_google_android_filament_View_nIsStencilBufferEnabled(JNIEnv *, jclass,
     return view->isStencilBufferEnabled();
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetStereoscopicOptions(JNIEnv *, jclass, jlong nativeView,
+        jboolean enabled) {
+    View* view = (View*) nativeView;
+    View::StereoscopicOptions options {
+        .enabled = (bool) enabled
+    };
+    view->setStereoscopicOptions(options);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,

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

@@ -111,6 +111,8 @@ public class Engine {
 
     private long mNativeObject;
 
+    private Config mConfig;
+
     @NonNull private final TransformManager mTransformManager;
     @NonNull private final LightManager mLightManager;
     @NonNull private final RenderableManager mRenderableManager;
@@ -163,6 +165,7 @@ public static class Builder {
         @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
         private final BuilderFinalizer mFinalizer;
         private final long mNativeBuilder;
+        private Config mConfig;
 
         public Builder() {
             mNativeBuilder = nCreateBuilder();
@@ -204,10 +207,11 @@ public Builder sharedContext(Object sharedContext) {
          * @return A reference to this Builder for chaining calls.
          */
         public Builder config(Config config) {
+            mConfig = config;
             nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
                     config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
                     config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
-                    config.jobSystemThreadCount);
+                    config.jobSystemThreadCount, config.stereoscopicEyeCount);
             return this;
         }
 
@@ -235,7 +239,7 @@ public Builder featureLevel(FeatureLevel featureLevel) {
         public Engine build() {
             long nativeEngine = nBuilderBuild(mNativeBuilder);
             if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-            return new Engine(nativeEngine);
+            return new Engine(nativeEngine, mConfig);
         }
 
         private static class BuilderFinalizer {
@@ -343,14 +347,24 @@ public static class Config {
          * the number of threads to use.
          */
         public long jobSystemThreadCount = 0;
+
+        /**
+         * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
+         * between 1 and Engine#getMaxStereoscopicEyes() (inclusive).
+         *
+         * @see View#setStereoscopicOptions
+         * @see Engine#getMaxStereoscopicEyes
+         */
+        public long stereoscopicEyeCount = 2;
     }
 
-    private Engine(long nativeEngine) {
+    private Engine(long nativeEngine, Config config) {
         mNativeObject = nativeEngine;
         mTransformManager = new TransformManager(nGetTransformManager(nativeEngine));
         mLightManager = new LightManager(nGetLightManager(nativeEngine));
         mRenderableManager = new RenderableManager(nGetRenderableManager(nativeEngine));
         mEntityManager = new EntityManager(nGetEntityManager(nativeEngine));
+        mConfig = config;
     }
 
     /**
@@ -543,6 +557,37 @@ public boolean isAutomaticInstancingEnabled() {
         return nIsAutomaticInstancingEnabled(getNativeObject());
     }
 
+    /**
+     * Retrieves the configuration settings of this {@link Engine}.
+     *
+     * This method returns the configuration object that was supplied to the Engine's {@link
+     * Builder#config} method during the creation of this Engine. If the {@link Builder::config}
+     * method was not explicitly called (or called with null), this method returns the default
+     * configuration settings.
+     *
+     * @return a {@link Config} object with this Engine's configuration
+     * @see Builder#config
+     */
+    @NonNull
+    public Config getConfig() {
+        if (mConfig == null) {
+            mConfig = new Config();
+        }
+        return mConfig;
+    }
+
+    /**
+     * Returns the maximum number of stereoscopic eyes supported by Filament. The actual number of
+     * eyes rendered is set at Engine creation time with the {@link
+     * Engine#Config#stereoscopicEyeCount} setting.
+     *
+     * @return the max number of stereoscopic eyes supported
+     * @see Engine#Config#stereoscopicEyeCount
+     */
+    public long getMaxStereoscopicEyes() {
+        return nGetMaxStereoscopicEyes(getNativeObject());
+    }
+
 
     // SwapChain
 
@@ -1171,6 +1216,7 @@ private static void assertDestroy(boolean success) {
     private static native long nGetEntityManager(long nativeEngine);
     private static native void nSetAutomaticInstancingEnabled(long nativeEngine, boolean enable);
     private static native boolean nIsAutomaticInstancingEnabled(long nativeEngine);
+    private static native long nGetMaxStereoscopicEyes(long nativeEngine);
     private static native int nGetSupportedFeatureLevel(long nativeEngine);
     private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
     private static native int nGetActiveFeatureLevel(long nativeEngine);
@@ -1180,7 +1226,8 @@ private static void assertDestroy(boolean success) {
     private static native void nSetBuilderBackend(long nativeBuilder, long backend);
     private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
             long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
-            long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount);
+            long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
+            long stereoscopicEyeCount);
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
     private static native long nBuilderBuild(long nativeBuilder);

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

@@ -75,6 +75,7 @@ public class View {
     private AmbientOcclusionOptions mAmbientOcclusionOptions;
     private BloomOptions mBloomOptions;
     private FogOptions mFogOptions;
+    private StereoscopicOptions mStereoscopicOptions;
     private RenderTarget mRenderTarget;
     private BlendMode mBlendMode;
     private DepthOfFieldOptions mDepthOfFieldOptions;
@@ -1055,6 +1056,51 @@ public boolean isStencilBufferEnabled() {
         return nIsStencilBufferEnabled(getNativeObject());
     }
 
+    /**
+     * Sets the stereoscopic rendering options for this view.
+     *
+     * <p>
+     * Currently, only one type of stereoscopic rendering is supported: side-by-side.
+     * Side-by-side stereo rendering splits the viewport into two halves: a left and right half.
+     * Eye 0 will render to the left half, while Eye 1 will render into the right half.
+     * </p>
+     *
+     * <p>
+     * Currently, the following features are not supported with stereoscopic rendering:
+     * - post-processing
+     * - shadowing
+     * - punctual lights
+     * </p>
+     *
+     * <p>
+     * Stereo rendering depends on device and platform support. To check if stereo rendering is
+     * supported, use {@link Engine#isStereoSupported()}. If stereo rendering is not supported, then
+     * the stereoscopic options have no effect.
+     * </p>
+     *
+     * @param options The stereoscopic options to use on this view
+     * @see #getStereoscopicOptions
+     */
+    public void setStereoscopicOptions(@NonNull StereoscopicOptions options) {
+        mStereoscopicOptions = options;
+        nSetStereoscopicOptions(getNativeObject(), options.enabled);
+    }
+
+    /**
+     * Gets the stereoscopic options.
+     *
+     * @return options Stereoscopic options currently set.
+     * @see #setStereoscopicOptions
+     */
+    @NonNull
+    public StereoscopicOptions getStereoscoopicOptions() {
+        if (mStereoscopicOptions == null) {
+            mStereoscopicOptions = new StereoscopicOptions();
+        }
+        return mStereoscopicOptions;
+    }
+
+
     /**
      * A class containing the result of a picking query
      */
@@ -1220,6 +1266,7 @@ void clearNativeObject() {
     private static native void nSetBloomOptions(long nativeView, long dirtNativeObject, float dirtStrength, float strength, int resolution, int levels, int blendMode, boolean threshold, boolean enabled, float highlight,
             boolean lensFlare, boolean starburst, float chromaticAberration, int ghostCount, float ghostSpacing, float ghostThreshold, float haloThickness, float haloRadius, float haloThreshold);
     private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, long skyColorNativeObject, boolean enabled);
+    private static native void nSetStereoscopicOptions(long nativeView, boolean enabled);
     private static native void nSetBlendMode(long nativeView, int blendMode);
     private static native void nSetDepthOfFieldOptions(long nativeView, float cocScale, float maxApertureDiameter, boolean enabled, int filter,
             boolean nativeResolution, int foregroundRingCount, int backgroundRingCount, int fastGatherRingCount, int maxForegroundCOC, int maxBackgroundCOC);

filament/include/filament/Engine.h

@@ -294,9 +294,10 @@ class UTILS_PUBLIC Engine {
 
         /*
          * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
-         * between 1 and CONFIG_MAX_STEREOSCOPIC_EYES (inclusive).
+         * between 1 and Engine::getMaxStereoscopicEyes() (inclusive).
          *
          * @see View::setStereoscopicOptions
+         * @see Engine::getMaxStereoscopicEyes
          */
         uint8_t stereoscopicEyeCount = 2;
     };
@@ -562,6 +563,29 @@ class UTILS_PUBLIC Engine {
      */
     bool isStereoSupported() const noexcept;
 
+    /**
+     * Retrieves the configuration settings of this Engine.
+     *
+     * This method returns the configuration object that was supplied to the Engine's
+     * Builder::config method during the creation of this Engine. If the Builder::config method was
+     * not explicitly called (or called with nullptr), this method returns the default configuration
+     * settings.
+     *
+     * @return a Config object with this Engine's configuration
+     * @see Builder::config
+     */
+    const Config& getConfig() const noexcept;
+
+    /**
+     * Returns the maximum number of stereoscopic eyes supported by Filament. The actual number of
+     * eyes rendered is set at Engine creation time with the Engine::Config::stereoscopicEyeCount
+     * setting.
+     *
+     * @return the max number of stereoscopic eyes supported
+     * @see Engine::Config::stereoscopicEyeCount
+     */
+    static size_t getMaxStereoscopicEyes() noexcept;
+
     /**
      * @return EntityManager used by filament
      */

filament/include/filament/View.h

@@ -691,11 +691,12 @@ class UTILS_PUBLIC View : public FilamentAPI {
      * - punctual lights
      *
      * Stereo rendering depends on device and platform support. To check if stereo rendering is
-     * supported, use Engine::isStereoSupported().
+     * supported, use Engine::isStereoSupported(). If stereo rendering is not supported, then the
+     * stereoscopic options have no effect.
      *
      * @param options The stereoscopic options to use on this view
      */
-    void setStereoscopicOptions(StereoscopicOptions const& options);
+    void setStereoscopicOptions(StereoscopicOptions const& options) noexcept;
 
     /**
      * Returns the stereoscopic options associated with this View.

filament/src/Engine.cpp

@@ -327,10 +327,18 @@ size_t Engine::getMaxAutomaticInstances() const noexcept {
     return downcast(this)->getMaxAutomaticInstances();
 }
 
+const Engine::Config& Engine::getConfig() const noexcept {
+    return downcast(this)->getConfig();
+}
+
 bool Engine::isStereoSupported() const noexcept {
     return downcast(this)->isStereoSupported();
 }
 
+size_t Engine::getMaxStereoscopicEyes() noexcept {
+    return FEngine::getMaxStereoscopicEyes();
+}
+
 #if defined(__EMSCRIPTEN__)
 void Engine::resetBackendState() noexcept {
     downcast(this)->resetBackendState();

filament/src/View.cpp

@@ -283,7 +283,7 @@ bool View::isStencilBufferEnabled() const noexcept {
     return downcast(this)->isStencilBufferEnabled();
 }
 
-void View::setStereoscopicOptions(const StereoscopicOptions& options) {
+void View::setStereoscopicOptions(const StereoscopicOptions& options) noexcept {
     return downcast(this)->setStereoscopicOptions(options);
 }
 

filament/src/details/Engine.h

@@ -184,6 +184,10 @@ class FEngine : public Engine {
 
     bool isStereoSupported() const noexcept { return getDriver().isStereoSupported(); }
 
+    static size_t getMaxStereoscopicEyes() noexcept {
+        return CONFIG_MAX_STEREOSCOPIC_EYES;
+    }
+
     PostProcessManager const& getPostProcessManager() const noexcept {
         return mPostProcessManager;
     }

filament/src/details/View.cpp

@@ -1126,9 +1126,7 @@ View::PickingQuery& FView::pick(uint32_t x, uint32_t y, backend::CallbackHandler
     return *pQuery;
 }
 
-void FView::setStereoscopicOptions(const StereoscopicOptions& options) {
-    ASSERT_PRECONDITION(!options.enabled || mIsStereoSupported,
-            "Stereo rendering is not supported.");
+void FView::setStereoscopicOptions(const StereoscopicOptions& options) noexcept {
     mStereoscopicOptions = options;
 }
 

filament/src/details/View.h

@@ -168,7 +168,9 @@ class FView : public View {
     bool hasDPCF() const noexcept { return mShadowType == ShadowType::DPCF; }
     bool hasPCSS() const noexcept { return mShadowType == ShadowType::PCSS; }
     bool hasPicking() const noexcept { return mActivePickingQueriesList != nullptr; }
-    bool hasInstancedStereo() const noexcept { return mStereoscopicOptions.enabled; }
+    bool hasInstancedStereo() const noexcept {
+        return mIsStereoSupported && mStereoscopicOptions.enabled;
+    }
 
     FrameGraphId<FrameGraphTexture> renderShadowMaps(FEngine& engine, FrameGraph& fg,
             CameraInfo const& cameraInfo, math::float4 const& userTime,
@@ -192,7 +194,7 @@ class FView : public View {
 
     bool isStencilBufferEnabled() const noexcept { return mStencilBufferEnabled; }
 
-    void setStereoscopicOptions(StereoscopicOptions const& options);
+    void setStereoscopicOptions(StereoscopicOptions const& options) noexcept;
 
     FCamera const* getDirectionalLightCamera() const noexcept {
         return mShadowMapManager.getDirectionalLightCamera();

libs/viewer/include/viewer/Settings.h

@@ -77,6 +77,7 @@ using TemporalAntiAliasingOptions = filament::View::TemporalAntiAliasingOptions;
 using VignetteOptions = filament::View::VignetteOptions;
 using VsmShadowOptions = filament::View::VsmShadowOptions;
 using GuardBandOptions = filament::View::GuardBandOptions;
+using StereoscopicOptions = filament::View::StereoscopicOptions;
 using LightManager = filament::LightManager;
 
 // These functions push all editable property values to their respective Filament objects.
@@ -192,6 +193,7 @@ struct ViewSettings {
     VignetteOptions vignette;
     VsmShadowOptions vsmShadowOptions;
     GuardBandOptions guardBand;
+    StereoscopicOptions stereoscopicOptions;
 
     // Custom View Options
     ColorGradingSettings colorGrading;
@@ -231,6 +233,7 @@ struct ViewerOptions {
     float cameraISO = 100.0f;
     float cameraNear = 0.1f;
     float cameraFar = 100.0f;
+    float cameraEyeOcularDistance = 0.0f;
     float groundShadowStrength = 0.75f;
     bool groundPlaneEnabled = false;
     bool skyboxEnabled = true;